chore(release): v3.26.2

Co-authored-by: Codex <noreply@openai.com>
fix(openai): keep turn rate limits scoped to the request
2026-11-07 16:05:27 +00:00 · 2026-10-14 16:16:30 +08:00 · 2026-10-14 16:01:49 +08:00 · 2026-10-14 15:54:47 +08:00 · 2026-10-14 14:30:58 +08:00 · 2026-10-14 13:50:51 +08:00
1571 changed files with 134233 additions and 51578 deletions
@@ -1,58 +1,55 @@
 ---
 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.
+description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和文档修改入口；PR、Issue、插件创作与发版按任务另用对应技能
 ---

 # 开发指南

-先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。
-本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。
+## 加载边界

-普通问题审查、代码审查与排查由本技能进入贡献文档的审查标准；有 PR 链接、编号或提交 PR 的意图时再加载 `cpr-github-pr`。
-审查请求先报告结论，不因加载开发技能而擅自修复；用户已要求修改时完成实现、自审和验证。
+- 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，上下文已有的规则不重复读取
+- 下表是条件导航，不是必读清单，只加载当前任务命中的技能与章节，进入新阶段再补读
+- 文档链接带 `#章节` 不代表读取工具会自动截取内容，先用 `rg -n '^#{1,4} ' 文件` 找边界，再按范围读取；常规定位不整份加载 CONTRIBUTING、架构、API、主题或全部 references，确需全文审查时再展开
+- 每次补读先明确要解决的未知项，已有资料足够就继续工作；文档提及 Rust、Vue、插件或发布，不等于要加载对应开发流程

 ## 按任务读取

-| 任务 | 技能与文档入口 |
+| 当前任务 | 必读的相关部分 |
 | --- | --- |
-| 用户能力、快速开始 | [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) |
+| 开发、排障、代码审查 | [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，需要定位代码时按 AGENTS 的 CodeGraph 约定执行 |
+| 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节，不通读整份架构 |
+| Rust 开发或审查 | `$rust-best-practices`、所属模块、[后端自审](../../../docs/architecture.md#后端自审)，验证时读[命令](../../../docs/architecture.md#验证命令) |
+| 页面开发 | `$frontend-design`、[前端职责](../../../docs/architecture.md#34-前端模块职责)、[文案与信息层级](../../../docs/theme.md#界面文案与信息层级)、[界面验证](../../../CONTRIBUTING.md#界面验证)；修改已有页面前留存截图，主题算法仅在涉及时读取 |
+| 接口、部署或迁移 | 分别定位 [API](../../../docs/api.md)、[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)的对应章节 |
+| SDK、Runtime、宿主扩展或独立插件 | [插件职责边界](references/plugin-boundaries.md)；只有创作、排查独立网关插件时使用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) |
+| 修改或审查文档 | [文档检查](references/documentation.md)及目标章节，不默认读取代码开发、页面验收或发布流程 |
+| 普通代码审查 | [审查标准](../../../CONTRIBUTING.md#审查标准)；审查默认只读 |
+| PR / Issue / 发版 | 按当前意图选 [PR](../cpr-github-pr/SKILL.md)、[Issue](../cpr-github-issue/SKILL.md)或[发版](../cpr-release/SKILL.md)，普通提交不创建 PR |

-## 前端任务
+## 参考仓库的优先级

- 加载并使用 `$frontend-design`，先读 [界面文案与信息层级](../../../docs/theme.md#界面文案与信息层级)，将本项目的管理工具风格、现有字体与主题 Token 作为设计约束
- 开发前对照原页面及该章节的同类参考，确认可复用布局、组件与操作位置；修改已有页面前先留存截图，不为局部需求重做页面
- 页面保留操作所需的简短信息，重复文案删除，详细帮助按主题约定收进 Popover；关键限制和错误仍就近提示
- 交付前按该章节复核文案、层级与密度，按 [界面验证](../../../CONTRIBUTING.md#界面验证) 实际操作并保存前后截图；页面 PR 的截图必须可供审查者访问，预览步骤与构建不能替代
+- 涉及 Codex 行为、协议或兼容性时，以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查官方实现
+- 优先使用用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档
+- 三方仓库只能提供排查线索或实现参考，不能代替官方行为依据；与官方不一致时回到官方源码核实，不直接照搬三方结论
+- 结论注明适用版本或提交，区分官方事实、三方参考与本项目推断；官方证据不足时保留不确定性

-## 后端任务
+## 执行与收尾

-加载并使用 `$rust-best-practices`，先按架构文档定位事实归属与既有调用链，实现后逐项执行 [后端自审](../../../docs/architecture.md#后端自审) 中与本次改动相关的检查。
-交付说明实际复用位置、重要边界的处理与验证缺口，不用“符合最佳实践”或“CI 已通过”代替自审结论。
+1. 确认工作区、任务范围与已有改动，先定位事实归属、同类实现和调用链，再修改；编码前只读[项目约定](../../../CONTRIBUTING.md#项目约定)的对应条目
+2. 自审完整差异，处理本次引入的职责越界、重复规则、冗余状态与无依据分支；仅审查时报告，不自行修复
+3. 按变更范围读取[验证](../../../CONTRIBUTING.md#验证)，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
+4. 交付说明实际结果与验证缺口；页面证据和后端生命周期检查按上表执行，不把构建通过当作行为验收

-## 执行顺序
+## 后端注释

-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` 流程整理最终证据与正文。
+- 每个 Rust 文件顶层使用简短的中文 `//!` 注释说明文件职责，覆盖生产源码、测试与构建脚本；测试文件说明测试范围或辅助用途，生成文件同步维护生成器
+- 注释不使用中文或英文句号，多句说明按语义分行；保留 URL、版本号、标识符和代码示例中有语义的点号
+- 文件说明聚焦当前功能与职责边界，局部注释解释原因和约束，避免复述代码或记录修改经过

-发布任务按 `cpr-release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。
+## 文档硬约束
+
+**常规文档只描述当前状态，不写变更历史**，这项检查适用于每次开发收尾，不限于专门的文档任务
+
+- 动笔前确定读者、所属章节与必须说明的当前事实，没有必要就不改文档
+- 有文档差异时执行[文档检查](references/documentation.md)，逐段决定保留、改写、删除或移入任务报告，未完成内容审查不能称文档已检查
+- 没有文档差异时只确认现有说明是否失真；普通开发不自动修改 `release/notes.md`
@@ -0,0 +1,38 @@
+# 文档检查
+
+仅在准备修改文档或最终差异含文档时读取，职责与行文依据是 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，只读该节
+
+## 写之前
+
+先明确这段内容服务谁、解决哪个当前使用或维护问题、属于哪个现有章节，再决定详略
+
+接口保留调用合同，架构保留职责与不变量，部署保留操作与排障；同一事实只在所属位置完整说明，其他位置链接
+
+常规文档在原章节修订，不追加本次变更小节，不为了“同步文档”补写修复总结
+
+内部重构、实现经过、前后对比、验证结果应留在 PR、Issue 或任务报告
+
+## 逐段验收
+
+检查工作区和暂存区中本任务的最终文档差异，按内容用途处理，不只搜索关键词：
+
+| 段落回答的问题 | 处理 |
+| --- | --- |
+| 现在如何使用、配置或理解结果 | 保留当前事实与必要边界，放回所属章节 |
+| 谁负责状态、事务、资源和失败处理 | 放入所属架构章节，避免在 API 或部署文档复述实现 |
+| 这次做了什么、以前怎样、为什么这样修、跑过哪些测试 | 移入 PR、Issue 或任务报告，不以换成现在时的方式留在常规文档 |
+| 特定配置或数据状态下如何升级、恢复 | 写明适用条件、操作及限制，删除演变过程 |
+| 别处已完整说明的事实 | 合并或改为必要摘要与链接 |
+
+脱离提交日期、Issue 和本次任务背景后，读者仍应能独立理解正文
+
+业务中的请求历史、审计记录、旧数据兼容与回滚操作是当前功能，不能因含“历史”“旧”等词而删除
+
+## 交付检查
+
+- 检查新段落的必要性、归属、重复与当前状态表达，发现变更叙述先改完再交付
+- 标题、短列表、表格和独立短段通常不加句号，长段按主题拆分，命令与字段保持准确
+- 检查相对链接、章节锚点、表格与命令示例，`git diff --check` 或构建通过不能代替内容审查
+- 报告实际覆盖和缺口即可，不把检查记录写进常规文档
+
+只有明确的发布说明任务才进入 `cpr-release`，`release/notes.md` 用于该次发行，不向 README、API、架构或部署文档复制版本变化列表
@@ -0,0 +1,11 @@
+# 插件职责边界
+
+仅在开发或审查 SDK、Runtime、宿主扩展接口及独立网关插件时读取
+先看[插件扩展](../../../../docs/architecture.md#31-插件扩展)中的职责与执行边界，不通读整份架构
+
+**宿主可以暴露底层能力，不能替插件完成业务**
+
+- 宿主提供可独立组合的受控原生能力，负责授权、资源隔离、事务与审计，复用已有服务与状态归属
+- 插件自身的触发条件、跨资源关联、策略和流程编排由插件实现，不能把某个使用场景做成宿主专属流程、状态或补偿逻辑
+- 发现能力缺口时，界定可独立使用的基础接口，说明输入输出、权限、事务、失败及重复调用语义，不夹带插件私有数据模型或工作流
+- 自审调用链、合同、测试与文档中的业务判断、自动串联和专属状态，仅换成通用名称不算解除耦合
@@ -1,61 +1,62 @@
 ---
 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.
+description: 草拟、创建、补充或回复 GitHub Issue，包括缺陷、功能和协作规则反馈；单独排障或修复不自动发布 Issue
 ---

-# 整理与提交 Issue
+# 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 和上下文确认接收仓库，fork 场景区分自己的仓库与上游

- 根据用户 URL、仓库上下文和 remote 确认接收 Issue 的仓库。fork 场景核对用户要反馈给自己的 fork 还是上游。
- “写一份、整理内容、草拟 Issue”只准备正文；明确要求“提交、创建 Issue”才发布。
-  已经授权提交且信息足够时直接完成，不重复索要确认；仅自动选中技能不能授权发布。
- “有个 bug”“这个报错怎么修”本身是排障语境，不能推断要发 Issue；结合已有反馈任务识别省略的目标和动作。
- “补充这个 Issue”先读取原帖与已有讨论，按授权更新正文或追加证据，不重复新建；需要排查或修改本仓库时先执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)。
- 缺少无法推断的目标或关键复现事实时，只问必要信息，并先整理其余已有证据。
- 使用可用的 GitHub 连接器或 `gh`。不要为提交 Issue 安装新工具、修改仓库配置或启用额外服务。
+草拟只准备正文，明确创建或提交才发布；已有授权直接执行，自动命中技能本身不授权远程写入

-## 证据与去重
+补充已有 Issue 先读原帖和讨论，按授权更新或追加，不重复新建；无法推断的目标或关键事实才向用户补齐

-1. 读取目标仓库实际 Issue 模板和配置，区分缺陷、功能建议与协作规则提案。
-   本仓库功能建议有独立表单，协作规则提案允许普通 Issue；其他仓库按其配置选择入口。
-2. 先搜索 open 和 closed Issues，结合关键词、错误信息与触发条件检查重复，而不只比较标题。
-   同时核对相关 PR 与发布记录，关联已有修复及其发布版本；仅主分支已修复时明确尚未发布。
-   同一问题已有记录且没有新增证据时返回已有链接；用户仍明确要求新建时按其要求处理。
-   不因发现重复而擅自评论、重开或关闭已有 Issue。
-3. 从用户描述、当前版本与已有诊断中整理事实：区分实际结果、预期结果、稳定复现条件和未经证实的推测。
-   不把本地开发版本当作发生问题的部署版本；无法复现时如实说明已知条件。
-   引用官方行为或提出实现方案时，按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 注明来源、版本与缺口；
-   不把找到官方源码或证明根因作为提交症状反馈的前提。
-4. 只收集定位所需信息。正文、日志片段和附件去除密钥、Cookie、令牌、代理认证、私人请求内容等敏感信息；
-   不直接附完整配置或请求转储。记录与复现相关的代理、TUN、证书条件，不擅自修改这些环境来收集材料。
+## 按需取材

-## 编写正文
+- 新建 Issue 时，本仓库只读[提交 Issue](../../../CONTRIBUTING.md#提交-issue)及本次匹配的一张表单：[接口问题](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml)或[功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml)；协作规则提案可用普通 Issue
+- 回复时读取原帖、相关讨论与支撑答复的证据，按下方回复口吻组织内容，不套用新建 Issue 的表单
+- 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING
+- 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理
+- 仅当需要额外排查或修改时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，提交症状反馈不以找到根因为前提
+- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；注明适用版本、来源与缺口

- 标题写具体症状或所需行为，不预先断言尚未证明的根因。语言与目标仓库及用户要求一致。
- YAML Issue Form 按字段顺序使用 `attributes.label` 作为 Markdown 小标题，填写相应答案。
-  `gh issue create --body-file` 直接提交正文，不会替你完成网页表单校验；手动核对必填字段、选项和必选确认项。
-  不把原始 YAML、占位文字或尚未确认的勾选项当成答案提交。
- 无法获知的信息明确写未提供或不适用，并说明理由；如果该事实关系到能否理解或复现问题，发布前补齐。
-  功能或规则提案说明当前场景、缺少的能力、建议结果和必要取舍，不强行填写缺陷复现步骤。
- 附件只使用用户授权发布且实际可访问的地址；本机 `/tmp/...` 路径不能作为 GitHub 附件。
-  没有可用附件时保留操作描述并说明缺口，不声称截图已上传。
- 使用模板规定或用户要求的 labels、assignees；先确认它们在目标仓库存在，不自行猜测。
+## 正文与证据

-## 提交与收尾
+标题说明症状或期望行为，区分发生问题的部署版本、实测结果、预期结果与根因假设

-把核对后的 UTF-8 正文写入临时文件，或直接传给连接器的结构化字段。CLI 变量先从已确认的目标与正文赋值：
+功能和规则提案说明场景、缺少的能力及建议结果，无需硬套缺陷复现步骤
+
+YAML 表单按 `attributes.label` 和字段顺序组织正文，手工核对必填项、选项与确认项，CLI 不会代做表单校验
+
+未知信息如实标明，影响理解或复现的关键事实先补齐，不提交原始 YAML、占位答案或未确认的勾选项
+
+日志和附件仅含定位所需的脱敏片段，不公开凭据、完整配置或请求转储，不擅自修改代理、TUN、证书环境取证
+
+附件须获授权且可访问，本机路径不算附件；labels 和 assignees 仅按模板或用户要求设置，并确认实际存在
+
+Issue 可记录复现、排查和变更经过，不因此向常规文档追加历史；确需改文档时执行[文档检查](../cpr-dev-guide/references/documentation.md)
+
+## 回复口吻
+
+草拟和发布 Issue 回复时遵守以下约定：
+
+- 用第一人称“我”表达，称呼对方为“佬友”，称呼自然出现即可，不逐句重复，也不用“我们”“本助手”代称自己
+- 语气客气、委婉，直接回应对方的具体问题；补充信息或提出不同意见时说明缘由，避免命令式、责备式表达
+- 使用自然短句，简单回复用短段，只有并列信息较多时才分点；少用句号，避免客服套话、机械模板和空泛保证
+- 只把实际完成的排查、复现和验证写成“我已……”；未确认的事实如实说明，委婉表达也要说清结论、限制和下一步
+
+## 发布与收尾
+
+使用可用连接器或 `gh`，不为提交反馈安装工具、修改仓库配置或启用服务
+
+多行正文通过结构化字段或 UTF-8 文件传递，以下变量须先从已确认的目标与正文赋值：

 ```bash
 gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
 ```

-发布前快速复核目标、必填内容、脱敏及重复记录；更新已有 Issue 时保留与本次无关的内容，核对目标编号和当前正文。
-网络超时或返回不明确时先查询远端是否已经创建或更新，避免重复提交。
-发布后读取目标 Issue 确认仓库、标题和正文，返回链接及必要的信息缺口。
-只准备草稿或发布失败时提供可直接使用的标题与正文，明确尚未提交。
+发布前核对目标、必填内容、脱敏与重复记录，更新时保留无关原文；不擅自评论、重开或关闭重复 Issue
+
+超时或结果不明确时先查询远端再重试，发布后回读确认并返回链接；仅草拟或发布失败时提供正文并注明未提交
@@ -1,121 +1,51 @@
 ---
 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.
+description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处理审查意见；普通 Git 提交和无 PR 上下文的排障不创建 PR
 ---

-# 提交、更新与审查 PR
+# PR 协作

-## 先确定模式和仓库
+## 先确定范围

-| 用户意图 | 执行范围 |
+沿用当前会话的目标与授权，创建 PR 包含任务范围内的提交和推送，审查默认只读；二者都不包含合并
+
+仅准备标题或正文不写远端，“能合并吗”按审查处理，发布评论、批准或请求修改须有对应授权
+
+从 URL、remote 和上下文确认仓库，区分 fork 的推送端与 PR 接收端；存在无法消除的歧义时只补齐必要信息
+
+本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求
+
+## 按模式读取
+
+只加载当前模式，已有上下文不重读；长文档先定位标题再截取对应章节，不因链接存在而加载全文或所有 references
+
+| 当前动作 | 读取与执行 |
 | --- | --- |
-| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 |
-| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR |
-| 提交到已有 PR、更新 PR、处理审查意见 | 按当前授权修改并验证，更新对应分支、正文与证据，不另建重复 PR |
-| 看下、审查 PR | 读取变更与证据，在当前会话报告 |
-| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 |
+| 只整理标题或描述 | 当前 PR、最终 diff、实际模板、[AI 披露](../../../CONTRIBUTING.md#ai-使用披露)，在授权范围内改文案；不读取推送或审查流程 |
+| 创建或更新 PR | [创建流程](references/create.md)、[PR 流程](../../../CONTRIBUTING.md#pr-流程)与[规则文件保护](../../../CONTRIBUTING.md#规则文件保护) |
+| 审查 PR | [审查流程](references/review.md)、[审查标准](../../../CONTRIBUTING.md#审查标准) |
+| 回复讨论或审查意见 | 目标评论、相关上下文与实际处理结果，按下方回复口吻答复；仅回复不加载创建或完整审查流程 |
+| 需要修改代码或文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应分支，完成自审与验证 |
+| 含页面改动 | [界面验证](../../../CONTRIBUTING.md#界面验证)，必需截图须可访问且对应当前实现 |
+| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md)，常规文档只说明当前状态，变更经过留在 PR |

-沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认；
-创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。
+## 回复口吻

-“看下这个”需结合已有 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#问题与方案依据)核实触发条件、发生版本与目标分支现状；涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考
+- 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR
+- 自审或审查覆盖完整差异与调用链，文档逐段检查必要性、职责、重复和当前状态表达，构建与链接检查不能代替内容判断
+- 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft
+- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只检查现有说明是否失真

-创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。
-用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。
+远程操作优先使用可用连接器，`gh` 显式指定 `--repo`，多行正文使用结构化字段或 `--body-file`

-核对最新目标分支及同一场景相关的 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。
+返回链接或会话内结论，说明实际范围与缺口，不将检查通过称为维护者批准
@@ -0,0 +1,35 @@
+# 创建或更新 PR
+
+仅在创建、推送或更新 PR 时读取，先完成[入口](../SKILL.md)的范围判断与公共核对
+
+1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
+   不用提交日志拼接正文，也不假定仓库一定有模板。
+2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
+   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
+3. 按入口的公共核对，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
+   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
+   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
+   按 `cpr-dev-guide` 完成实现自审；后端按 [后端自审](../../../../docs/architecture.md#后端自审) 核对归属、状态、失败出口与副作用，
+   页面先复用已有设计并检查文案密度。处理本次引入的冗余与越界问题，功能可用和检查通过不能替代可维护性自查。
+4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
+   更新现有标题或正文须在本次整理/更新请求范围内。
+5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
+   有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 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 命令。
+创建完成返回链接、目标分支和验证摘要；不要称为已合并或已获维护者批准。
@@ -0,0 +1,33 @@
+# 审查 PR
+
+仅在审查 PR 时读取，执行[入口](../SKILL.md)的公共核对，默认只在当前会话报告
+
+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；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
+   有文档差异时按[文档检查](../../cpr-dev-guide/references/documentation.md)检查最终 diff，不能把构建或链接检查通过当作文档内容已经合格。
+   核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
+7. 按 [审查标准](../../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
+   再列出实现问题与验证缺口，结论附具体依据。
+   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
+   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
+   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
+8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
+
+审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
+用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
+需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。
@@ -1,85 +1,40 @@
 ---
 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.
+description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改宿主 Runtime、安装器或管理端时使用 cpr-dev-guide，不适用于 Codex 插件或 Vue 插件
 ---

-# cpr-plugin-dev
+# 网关插件开发

-面向插件作者。插件在独立项目中实现，通过公开 SDK 与宿主通信，不向宿主业务模块添加分支。
-仅修改宿主安装器、Runtime 或管理端时，使用仓库开发指南，不按本技能创建插件工程。
-本仓库开发与排查同时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，准备、提交或审查插件 PR 时执行 [cpr-github-pr](../cpr-github-pr/SKILL.md)。
+插件在独立项目中通过公开 SDK 实现业务，不向宿主业务模块添加专属流程

-## 先建立正确的模型
+同时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的对应任务分支，已加载则复用，不递归重读

-```text
-选择能力 → 作者清单 + SDK 处理器 → 构建二进制／页面 → cpr-plugin package
-                                                       ↓
-实际业务验证 ← 查看权限并安装、自动准备配置 ← tar.gz + sha256
-```
+## 范围与合同

- `contributes` 声明提供什么，`permissions` 声明访问域；安装接受记录派生授权，`bindings` 只决定功能挂载和请求匹配
- 安装包、运行配置和已启用功能不是同一件事；安装成功不能代替功能验证
- `trustedProcess` 与宿主使用相同系统身份，不是操作系统沙箱
+- 确认用途、工程位置、目标宿主版本与平台，沿用已有工程；位置无法推断时只补齐该信息，不把插件源码塞进宿主 workspace
+- 核对运行宿主、[SDK 版本](../../../backend/crates/gateway-plugin/sdk/Cargo.toml)、[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)及所用 CLI，清单、进程和能力版本分别判断
+- `contributes` 声明处理器，`bindings` 选择挂载与匹配范围；安装成功不等于功能生效。当前清单拒绝 `permissions`，安装者完整信任插件，`trustedProcess` 不提供操作系统沙箱或访问域隔离，见[完整信任](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任)
+- 涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；宿主能力以目标版本的 SDK 为准

-## 开始工作
+## 按当前步骤读取

-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#发布与安装来源)
+只读取命中行与链接的指定章节，长文档先列标题再截取；不预读全部 SDK、示例、前端和打包资料

-本技能相对链接以各文件所在目录解析；主仓根目录是本文件所在目录向上三级。插件工程或同级示例不在磁盘上时，请用户提供位置或使用选定版本的公开资料，不猜开发机绝对路径，也不自动克隆或创建远程仓库。
-
-## 按任务选择能力
-
-| 用户要做什么 | 优先使用 | 需要读取的合同 |
-| --- | --- | --- |
-| 改写请求／响应、处理流式内容、协议转换 | `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 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本
+| 当前工作 | 入口 |
+| --- | --- |
+| 选择能力或确认能力缺口 | [能力与方法](../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)、所需能力章节、[插件职责边界](../cpr-dev-guide/references/plugin-boundaries.md) |
+| 清单与 Rust 处理器 | [实现参考](references/implementation.md)、所用 SDK 类型；只有修改清单字段时读[清单](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md)对应章节 |
+| 创建或修改页面 | [页面参考](references/frontend.md)，不需要页面的插件不创建前端 |
+| 准备工程或联调依赖 | [工程与依赖](references/development.md#工程与依赖)，需要示例时再读[复用示例](references/development.md#复用示例) |
+| 构建或打包 | [构建与打包](references/development.md#构建与打包) |
+| 实际验收 | [验证与交付](references/development.md#验证与交付)，按实现范围验证 |
+| 分发插件 | [发布与安装来源](references/development.md#发布与安装来源)，不自动进入宿主发版流程 |
+| 修改插件文档 | [文档检查](../cpr-dev-guide/references/documentation.md)，只写当前用法、合同和限制，不附修复过程 |

 ## 交付

-按[构建与验证](references/development.md#验证与交付)提供源码位置、能力／权限／绑定摘要、实际运行结果及验证缺口。
-开发插件不默认授权安装并启用本机进程、调用真实上游、发布依赖或推送仓库；超出当前授权时交付可安装包及操作步骤。
+说明源码与产物位置、兼容范围、能力与绑定、实际验证及缺口，只报告真正生成的安装包或完成的业务验证
+
+修改源码不默认授权在目标实例安装启用、调用真实上游或发布，沿用用户当前授权判断后续动作
+
+PR 任务才使用 [cpr-github-pr](../cpr-github-pr/SKILL.md)，文档检查按开发入口收尾执行
@@ -1,6 +1,7 @@
 # 构建、联调与验证

-仅在准备工程、构建或验证插件时读取。这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册。
+仅在准备工程、构建或验证插件时读取对应章节，分发规则只在准备分发时读取
+这里给出执行入口，不复制 SDK 协议或安装 API 的字段手册

 ## 工程与依赖

@@ -11,11 +12,11 @@
 | [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 对应合同起步，不给示例添加无关能力。
+先检查用户给定工程、`modules/plugins` 子模块或同级仓库是否存在，读取实际仓库约定及当前步骤所需的 README 章节、依赖与锁文件，不预读无关前端配置
+只需中间件时不复制示例的管理 API 和页面；CLI 等能力从 SDK 对应合同起步，不给示例添加无关能力

-本地源码联调可以使用 Cargo 路径依赖和 pnpm 的包级链接／override；路径必须真实可解析，并记录在消费方依赖配置中。
-这不等于允许从业务源码跨仓 `import .../src/...`，也不能证明第三方能独立安装。
+本仓库子模块联调使用[开发文档](../../../../docs/development.md#源码联调)中的 source 模式和本地 SDK 验证入口，不改写正式依赖或锁文件
+其他工程按其自身联调配置临时使用包级链接或 override，路径须真实可解析，不从业务源码跨仓 `import .../src/...`

 对外交付前核实 UI／SDK 的可用版本和安装来源：仅引用确实存在的发布版本，或包含所需合同的固定 Git commit；
 不要把浮动 `main` 当版本，也不要自动发布依赖以补齐条件。本地 override 尚未移除时，明确说明独立安装缺口。
@@ -23,7 +24,7 @@

 ## 复用示例

-找到 `codex-proxy-plugins` 后先读根目录与 `examples/workbench/README.md`。
+找到 `codex-proxy-plugins` 后，只读根目录约定与 `examples/workbench/README.md` 中当前能力或构建所需的章节
 该仓库使用 `bash scripts/package` 构建页面、Rust 二进制并打包；前端依赖和工具配置位于示例的 `frontend/`，根目录不维护 Node 工程。执行前核对脚本适用的插件路径和目标平台。

 | 任务 | 示例入口 |
@@ -36,7 +37,7 @@
 | 包内静态资源构建 | `examples/workbench/frontend/vite.config.ts` |

 若派生新插件，同时修改包名、二进制名、插件身份、扩展项 ID、注册描述和构建目标，不只改展示名称。
-保留当前项目确实需要的依赖、资源和权限；不要把示例中的全请求范围直接用到共享环境。
+保留当前项目确实需要的依赖、资源和能力声明；不要把示例中的全请求范围直接用到共享环境

 ## 构建与打包

@@ -57,7 +58,7 @@ cargo build --manifest-path /path/to/plugin/Cargo.toml --release --locked --targ
 需要从目标宿主源码构建工具时，在主仓根目录运行以下命令，把 `--help` 换成实际参数即可，不必全局安装：

 ```bash
-cargo run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+cargo +1.97.0 run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
 ```

 直接打包的示意命令：
@@ -91,7 +92,7 @@ cpr-plugin package \

 ## 验证与交付

-按[插件使用](../../../../docs/plugins.md)验证“安装包 → 查看权限并安装 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加授权或资源选择向导。
+按[插件使用](../../../../docs/plugins.md)验证“校验安装包 → 确认来源并接受完整信任 → 自动准备默认配置 → 实际使用”；只在缺少业务必填值时补配置，不添加权限或资源选择向导
 只有获得目标环境操作授权才安装和启用；不把修改源码的授权扩展到生产实例或真实凭据操作。
 需要 API 自动化时查[插件管理 API](../../../../docs/api.md#12-插件管理)，不要依据记忆拼路由。

@@ -99,7 +100,8 @@ cpr-plugin package \

 | 实现范围 | 应验证的行为 |
 | --- | --- |
-| 中间件 | 匹配／不匹配范围、授权不足、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| 中间件 | 匹配／不匹配范围、单次 `next`、未改写字节保留、下游错误与取消；支持流式时检查多帧、终态和断开；若涉及续链，使用真实目标客户端检查 HTTP/SSE、WS 及后续轮次 |
+| 上游适配器 | 绑定匹配、账号认证与代理、HTTP/SSE 或 WS 事件解析、发送状态、用量和终态；支持续接时核对 Key、账号、凭据版本与代次隔离，失败不能透明重放已发送操作 |
 | 模型路由／调度 | 真实入口能命中规则，未匹配请求保持原有行为；使用官方客户端正常携带的业务头和会话别名，确认投影不会拒绝合法请求，也不暴露身份字段 |
 | 生命周期／用量／WS 观察 | 完成一次实际模型请求并核对对应事件；WS 观察需确认实际上游采用 WS，HTTP 请求成功不能证明 WS 观察生效 |
 | 管理页面 | 从宿主打开，标题／副标题、明暗主题、加载与错误状态；管理桥请求成功；停用或版本切换后旧入口失效 |
@@ -110,5 +112,5 @@ cpr-plugin package \
 外部示例测试若依赖未提供的仓库或制品，应记录为未执行；当前示例可用于实际能力联调，但不能把被忽略的测试计为通过。
 临时账号、Key 或配置只在明确的测试范围内创建，记录并清理自己创建的对象，不输出密钥、原始请求或插件 secret。

-交付简述：源码与产物位置、兼容范围、所需能力／权限／绑定、执行过的命令及结果、尚未验证的场景。
+交付简述：源码与产物位置、兼容范围、所需能力与绑定、执行过的命令及结果、尚未验证的场景
 只有确实生成了产物才报告“已打包”，只有目标环境业务验证成功才报告“已生效”；提交、推送与发布按用户授权另行执行。
@@ -0,0 +1,11 @@
+# 插件页面
+
+仅在创建或修改插件页面时读取，同时使用[开发入口](../../cpr-dev-guide/SKILL.md)的页面分支
+
+- 沿用已有插件页面与 [管理端主题](../../../../docs/theme.md#界面文案与信息层级) 的设计和文案层级，详细帮助使用现有 Popover；页面 PR 按 [界面验证](../../../../CONTRIBUTING.md#界面验证) 提供实际截图
+- 优先参考独立示例仓库的 `examples/workbench/frontend/src/api/`：业务路由放在 `modules/`，`request.ts` 封装公开宿主桥；按需使用 `@codex-proxy/ui` 包出口，不跨仓导入宿主或 UI 的内部源码
+- Vue 页面保留 SFC，逻辑、脚本和配置使用 TypeScript；只实现业务内容，标题和副标题由 `ManagementPage` 交给宿主显示
+- 隔离页面通过 `window.codexProxyPlugin.request` 调用已注册管理路由；`models.responses` 通过普通请求链交付 JSON/SSE，支持取消且不暴露 Key 明文。不直接 `fetch` 宿主、不读取管理 Cookie 或借用宿主 Vue 实例
+- 管理路由的响应正文由插件业务定义，不默认套用宿主管理 API 的 `{ code, message, data }`；页面与处理器共享实际合同，GET 无正文时不附带 JSON 正文声明
+- `host.model.*` 子请求跳过发起插件，不能用它证明本插件中间件／路由已参与；需要完整请求链的示例使用页面模型桥或真实客户端
+- JS、CSS、图标等资源随包构建和声明；沿用宿主桥的主题同步。Vite 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本
@@ -0,0 +1,25 @@
+# 清单与处理器实现
+
+仅在编写或排查插件清单、Rust 处理器时读取，涉及 Rust 时使用[开发入口](../../cpr-dev-guide/SKILL.md)的 Rust 分支
+选择能力时只读 SDK 的[能力与方法](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所需能力章节
+
+## 清单与处理器
+
+- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果
+- `contributes` 每种能力最多一项，普通贡献项可省略派生 ID、能力版本和固定阶段；中间件必须声明版本 `4` 并显式选择阶段，上游适配器必须声明版本 `2`。自定义完整扩展项 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／取消／流控机制；HTTP、WebSocket、服务和模型请求按各自的类型化视图处理
+- 持久化状态使用已声明命名空间的 `host.state.*`，账号读写使用 `host.auth.*`，不直接访问宿主数据库。见[账号与凭据](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#账号与凭据)和[状态、日志与迁移](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#状态日志与迁移)
+- 按[完整信任](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任)使用宿主回调，不添加权限或访问域声明；资源选择属于插件业务，父调用、期限、取消、实例 revision 与事务校验仍须满足
+- 模型、网络和亲和查询使用当前父调用的受管回调。管理／CLI 等独立入口调用模型时传明确的 Key ID；请求处理阶段继承父身份。见[Key、模型与模型调用](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#key模型与模型调用)
+- SDK 操作名不是管理员 HTTP 路由，不能据此拼接口地址；主动调用 HTTP 使用 `dispatch_http`，类型化服务使用 `HostClient::service`，实际执行与账单事实仍由宿主持有
+- 路由与调度只读取宿主投影的请求事实，身份头可能被隐藏；使用已有会话和亲和合同，不依赖原始认证头或根据缓存键补造客户端身份
+- 需要自定义上游编码、路径与响应解析时使用[受管上游适配器](../../../../backend/crates/gateway-plugin/sdk/docs/upstream-adapters.md)，它是已选号后的终端，不调用 `next` 或自行组织换号重试；普通请求和响应加工仍使用中间件
@@ -1,110 +1,38 @@
 ---
 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.
+description: Codex Proxy RS 的版本规划、发布说明、正式或预发行发布与失败恢复；部署重启和普通 Git tag 清理不属于发版
 ---

 # 发版

-## 识别任务范围
+## 范围与授权

-| 用户意图 | 执行范围 |
+沿用用户确定的版本、范围与授权，准备版本或询问能否发布不执行远程写入；明确发布时完成已授权步骤，无需重复确认
+
+仅打 tag 不自动扩展为完整发版，发布也不包含运行实例升级或合并实验功能
+
+稳定版与 alpha、beta、rc 从 `main` 发布，exp 从对应 `experimental/<用途>` 分支发布
+
+其他仓库使用其发布入口与规则，不套用本仓库路径；规则已在上下文中时不重复读取
+
+## 按任务读取
+
+只读当前阶段和指定章节，先定位标题再截取，不预读整份 CONTRIBUTING、工作流或所有参考文件；实际发布前仍须核对发布入口的完整副作用
+
+| 任务 | 读取范围 |
 | --- | --- |
-| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 |
-| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 |
-| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 |
-| 发布 alpha、beta、rc | 从 `main` 发布，确定目标正式版本和阶段，核对预发行标记与晋级路径 |
-| 发布实验版、exp 版本 | 从目标实验分支发布，按下方实验版流程确定版本、文案和渠道隔离 |
-| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 |
+| 推荐版本号 | [基线与版本](references/preparation.md#基线与版本) |
+| 编写或翻译发布说明 | [基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明) |
+| 检查发行条件 | [发行准备检查](references/preparation.md#发行准备检查) |
+| 实际发布 | 完成准备，再读[通道核对](references/operations.md#发行通道核对)和[执行发版](references/operations.md#执行发版) |
+| 失败恢复或验收 | [恢复与验收](references/operations.md#恢复与验收)，先确定已完成步骤，不直接重跑入口 |
+| 实验版 | 在对应阶段补读[实验流程](references/experimental.md)的版本、文案或验收章节 |
+| 修复代码、工作流或常规文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，有 PR 任务再使用 [cpr-github-pr](../cpr-github-pr/SKILL.md) |

-沿用当前会话明确的版本、范围与授权；用户已授权发布目标版本且条件满足时直接执行，不重复确认。
-“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。
-发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。
-需要修复本仓库代码、工作流或文档时先执行 [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 和镜像已生成也不表示用户的运行实例已经升级。
+- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练
+- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
+- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
+- `release/notes.md` 只承载当前发行的说明，常规文档只写当前状态，不追加版本历史；其变更执行[文档检查](../cpr-dev-guide/references/documentation.md)
+- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功
@@ -1,7 +1,7 @@
 # 实验版发布

-适用于独立于主版本维护、供用户主动选择体验的实验功能。发布入口仍是仓库的 `release/publish`，
-构建复用目标实验分支的 `.github/workflows/release.yml` 与 `release/platforms.yaml`。
+按当前任务只读版本、发布能力、文案或验收章节，不因准备实验说明而读取执行流程
+适用于独立于主版本维护、供用户主动选择体验的实验功能，入口使用仓库的 `release/publish`，构建复用目标实验分支的工作流与平台清单

 ## 分支与版本

@@ -14,10 +14,10 @@
  不为统一名称移动 tag 或替换原有产物。
 - GitHub Release 展示标题采用 `vX.Y.Z-<用途>.M`，`<用途>` 取实验分支名去掉 `experimental/` 前缀后的部分。
  发布前通过 `gh api` 核对相同正式版基线与用途的已有 Release 标题和旧命名 tag，新发行取已有最大编号加 1，首次从 1 开始。
-  展示编号 `M` 独立于实际 tag 的 `exp.N`，旧命名发行也计入，不能因改用 `exp.N` 而重置；同一发行重试沿用已确定编号。
+  展示编号 `M` 独立于实际 tag 的 `exp.N`，所有同基线、同用途的已有发行均计入，不随 tag 命名格式重置；同一发行重试沿用已确定编号。
  例如已有 `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。
+  发布说明首行匹配实际 tag，关联 Issue 和试验目的写在正文中，已有 Release 不因新发行而改名

 ## 先核对发布能力

@@ -54,12 +54,12 @@

 ## 执行与验收

-按主技能准备说明和其他变更后，在实验分支执行 `release/publish <X.Y.Z-exp.N>`。
+按[版本与说明准备](preparation.md)的对应章节准备后，再按[执行发版](operations.md#执行发版)在实验分支调用入口
 入口创建版本提交和 tag，并从该分支 dispatch 发布工作流；不要从 `main` 发布实验代码。

-按主技能的「发行通道核对」确认稳定入口未改变，并检查实验线隔离与上一版本的更新能力。
+按[发行通道核对](operations.md#发行通道核对)确认稳定入口未改变，并检查实验线隔离与上一版本的更新能力。
 检查展示标题的分支用途与历史续号、它所对应的实际 tag，以及目标 tag 的源码提交、完整产物、校验和、多架构平台和 Pre-release 标记。
 同基线的 `X.Y.Z-exp.N` 按 SemVer 排序低于正式 `X.Y.Z`；渠道隔离仍以更新器过滤和发布标签规则为准。

-失败时按主技能从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。
+失败时按[恢复与验收](operations.md#恢复与验收)从未完成步骤恢复，不通过换版本号或移动 tag 掩盖失败。
 仅维护已有页面文案时不重新构建；报告实际完成状态、发布链接及验证缺口。
@@ -0,0 +1,49 @@
+# 执行、恢复与验收
+
+只在实际发布、恢复失败步骤或验收发行时读取对应章节，先核对[入口](../SKILL.md)中的范围与授权
+
+## 发行通道核对
+
+- 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`；被禁止的目标即使版本领先，也不能出现在更新标记、可用版本或发布说明中。
+  检查失败须单独报告。核对上一发行实际包含的更新能力，不能因新包支持在线更新就宣称旧包也能在线安装它。
+
+## 执行发版
+
+调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
+先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。
+脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。
+不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
+本任务需要的提交按[项目约定](../../../../CONTRIBUTING.md#项目约定)保留英文 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 和镜像已生成也不表示用户的运行实例已经升级。
@@ -0,0 +1,36 @@
+# 版本与说明准备
+
+只在规划版本、编写发布说明或准备发行时读取对应部分，不因准备文案加载执行流程
+
+## 基线与版本
+
+1. 确认类型、分支、upstream、目标仓库、工作区与完整待发布范围，保留无关改动；未跟踪文件也需核对
+2. 读取 [version.yaml](../../../../release/version.yaml)、相关 tag 和实际 Release，确定上一发布基线与本次目标提交，再核对二者间的最终 diff，不只看最近几条提交
+3. 使用用户确定的目标版本，建议版本时说明兼容性、能力或修复依据；同名 tag 先区分重试与新发行，不递增版本掩盖冲突
+4. 命名与晋级按[版本命名与升级规则](../../../../deploy/README.md#版本命名与升级规则)，实验版另读[实验流程](experimental.md#分支与版本)
+
+## 发布说明
+
+读取当前 [notes.md](../../../../release/notes.md)与[项目约定](../../../../CONTRIBUTING.md#项目约定)中的发布说明条目
+
+- 只在发布说明任务中修改 `release/notes.md`，替换为本次版本内容，首行为目标 tag，正文使用中文
+- 按用户可感知的最终变化归并，省略空章节，不逐条翻译提交，不写排查过程或未经验证的承诺
+- 剔除回退、重复及未进入发行范围的内容，升级事项须能追溯到实际迁移、配置或兼容变化
+- 只翻译已有准确说明时保持事实与范围，不混入其他变更
+- 常规文档仍只描述当前状态；必要修订执行[文档检查](../../cpr-dev-guide/references/documentation.md)，不复制发布说明中的版本变化列表
+
+实际发布由 `release/publish` 提交说明与版本文件，准备说明时不要提前单独提交或把版本文件改成目标版本
+用户只要求准备时保留本地改动，纯说明修改无需重建前后端
+
+## 发行准备检查
+
+进入实际发行准备后，读取目标分支的 [release/publish](../../../../release/publish)、[工作流](../../../../.github/workflows/release.yml)与[平台清单](../../../../release/platforms.yaml)，按当前入口执行，不另写脚本或绕过检查
+
+按[验证要求](../../../../CONTRIBUTING.md#验证)核对目标提交的证据，区分通过、失败、跳过与未执行
+数据库变更同时读取[迁移冻结规则](../../../../backend/migrations/README.md#冻结规则)：
+
+- 对照同一大版本的上一正式版和本轮预发行／实验线的已发布版本，验证迁移未改写及升级路径
+- 区分未发布迁移、已执行迁移的源码部署实例与 CI 冻结基线，未发版不代表未执行，也不授权放宽冻结规则
+- 兼容性与 CI 检查分别报告，跨大版本不默认支持在线升级
+
+正式执行时再读取[通道核对](operations.md#发行通道核对)与[执行发版](operations.md#执行发版)，触发工作流不等于发布成功
@@ -0,0 +1,41 @@
+name: Build frontend
+description: Validate and build the frontend, optionally uploading release assets
+inputs:
+  upload-artifact:
+    description: Upload frontend-dist for downstream release jobs
+    default: 'false'
+runs:
+  using: composite
+  steps:
+    - 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
+        cache: pnpm
+        cache-dependency-path: frontend/pnpm-lock.yaml
+
+    - name: Install frontend dependencies
+      shell: bash
+      run: pnpm --dir frontend install --frozen-lockfile
+
+    - name: Frontend format
+      shell: bash
+      run: pnpm --dir frontend format:check
+
+    - name: Frontend build
+      shell: bash
+      run: pnpm --dir frontend build
+
+    - name: Upload frontend artifact
+      if: inputs.upload-artifact == 'true'
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: frontend-dist
+        path: frontend/dist
+        if-no-files-found: error
+        retention-days: 1
@@ -0,0 +1,27 @@
+# syntax=docker/dockerfile:1.7@sha256:a57df69d0ea827fb7266491f2813635de6f17269be881f696fbfdf2d83dda33e
+
+FROM busybox:1.37.0-musl@sha256:5cec3fc171c87218698e85a52af7087de727372aae264a787b8112901a5b0092 AS restore
+ARG CACHE_STAMP
+RUN --mount=type=bind,target=/cache \
+    --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/usr/local/cargo/git \
+    --mount=type=cache,target=/app/backend/target \
+    test -n "$CACHE_STAMP" \
+    && cp -a /cache/registry/. /usr/local/cargo/registry/ \
+    && cp -a /cache/git/. /usr/local/cargo/git/ \
+    && cp -a /cache/target/. /app/backend/target/
+
+FROM busybox:1.37.0-musl@sha256:5cec3fc171c87218698e85a52af7087de727372aae264a787b8112901a5b0092 AS collect
+ARG CACHE_STAMP
+# 一次导出三个 mount，避免逐目录创建镜像、载入 Docker 再复制文件。
+RUN --mount=type=cache,target=/usr/local/cargo/registry \
+    --mount=type=cache,target=/usr/local/cargo/git \
+    --mount=type=cache,target=/app/backend/target \
+    test -n "$CACHE_STAMP" \
+    && mkdir -p /cache/registry /cache/git /cache/target \
+    && cp -a /usr/local/cargo/registry/. /cache/registry/ \
+    && cp -a /usr/local/cargo/git/. /cache/git/ \
+    && cp -a /app/backend/target/. /cache/target/
+
+FROM scratch AS snapshot
+COPY --from=collect /cache/ /
@@ -0,0 +1,31 @@
+name: Cargo cache mounts
+description: Restore or export a validated Cargo snapshot for a BuildKit builder
+inputs:
+  operation:
+    description: Cache operation, restore or snapshot
+    required: true
+  builder:
+    description: Buildx builder name
+    required: true
+  path:
+    description: Cargo snapshot directory on the runner
+    required: true
+  architecture:
+    description: Cargo target directory architecture, amd64 or arm64
+    required: true
+outputs:
+  usable:
+    description: Whether the restored or exported snapshot contains Cargo dependencies
+    value: ${{ steps.cache.outputs.usable }}
+runs:
+  using: composite
+  steps:
+    - id: cache
+      shell: bash
+      env:
+        ACTION_PATH: ${{ github.action_path }}
+        OPERATION: ${{ inputs.operation }}
+        BUILDER: ${{ inputs.builder }}
+        CACHE_PATH: ${{ inputs.path }}
+        ARCHITECTURE: ${{ inputs.architecture }}
+      run: bash "$ACTION_PATH/cargo-cache.sh" "$OPERATION" "$BUILDER" "$CACHE_PATH" "$ARCHITECTURE"
@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ "$#" -ne 4 ]; then
+  echo "usage: $0 restore|snapshot BUILDER DIRECTORY amd64|arm64" >&2
+  exit 2
+fi
+operation="$1"
+builder="$2"
+directory="$(realpath -m "$3")"
+architecture="$4"
+case "$operation" in restore|snapshot) ;; *) exit 2 ;; esac
+case "$architecture" in amd64|arm64) ;; *) exit 2 ;; esac
+dockerfile="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/Dockerfile"
+
+usable() {
+  local root="$1" path crates=false libraries=false
+  # 目录或 buildstamp 存在不代表编译发生过，必须同时有下载包与目标依赖。
+  for path in "$root"/registry/cache/*/*.crate; do
+    if [ -f "$path" ] && [ -s "$path" ]; then crates=true; break; fi
+  done
+  for path in "$root"/target/"$architecture"/release/deps/*.rlib; do
+    if [ -f "$path" ] && [ -s "$path" ]; then libraries=true; break; fi
+  done
+  [ "$crates" = true ] && [ "$libraries" = true ]
+}
+
+command=(docker buildx build --builder "$builder" --file "$dockerfile" --progress plain)
+# mount 的内容不参与层指纹，用时间戳重跑复制；--no-cache 会重置 cache mount。
+command+=(--build-arg "CACHE_STAMP=$(date +%s%N)" --target "$operation")
+valid=false
+if [ "$operation" = restore ]; then
+  if usable "$directory"; then
+    mkdir -p "$directory"/{registry,git,target}
+    "${command[@]}" --output type=cacheonly "$directory"
+    valid=true
+  else
+    echo "No usable Cargo snapshot; cached image layers may still be available"
+  fi
+else
+  # 导出只发送空上下文，新快照独立校验后替换旧目录，避免残留文件造成误判。
+  mkdir -p "$(dirname "$directory")"
+  temporary="$(mktemp -d "${directory}.XXXXXX")"
+  trap 'rm -rf "$temporary"' EXIT
+  mkdir "$temporary/context"
+  "${command[@]}" --output "type=local,dest=$temporary/snapshot" "$temporary/context"
+  if usable "$temporary/snapshot"; then
+    rm -rf "$directory"
+    mv "$temporary/snapshot" "$directory"
+    valid=true
+  fi
+fi
+
+echo "Cargo snapshot for $architecture: usable=$valid"
+if [ "$valid" = true ]; then du -sh "$directory"; fi
+if [ -n "${GITHUB_OUTPUT:-}" ]; then printf 'usable=%s\n' "$valid" >> "$GITHUB_OUTPUT"; fi
@@ -117,8 +117,9 @@ runs:
        compose=(docker compose --project-name "$COMPOSE_PROJECT_NAME" \
          -f deploy/compose.yaml)
        "${compose[@]}" up -d --no-build --wait postgres redis
+        # 基础设施使用 UTC，业务展示和调度时区由应用配置独立控制。
        test "$("${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
-          psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = Asia/Shanghai
+          psql -At -U codex_proxy -d codex_proxy -c "SHOW TimeZone;" | tr -d '\r')" = UTC
        "${compose[@]}" exec -T -e PGPASSWORD="$CI_POSTGRES_PASSWORD" postgres \
          psql -v ON_ERROR_STOP=1 -U codex_proxy -d codex_proxy -c \
          "CREATE TABLE cpr_ci_persistence_probe (value text PRIMARY KEY); INSERT INTO cpr_ci_persistence_probe VALUES ('persisted');"
@@ -148,8 +149,8 @@ runs:
        test "$status" = 204
        test "$("${compose[@]}" exec -T codex-proxy-rs id -u | tr -d '\r')" = 10001
        test "$("${compose[@]}" exec -T codex-proxy-rs id -g | tr -d '\r')" = 10001
-        test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0800
-        test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = Asia/Shanghai
+        test "$("${compose[@]}" exec -T codex-proxy-rs date +%z | tr -d '\r')" = +0000
+        test "$("${compose[@]}" exec -T codex-proxy-rs cat /etc/timezone | tr -d '\r')" = UTC
        "${compose[@]}" exec -T codex-proxy-rs sh -c \
          'touch /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write && rm /app/.runtime/data/.ci-write /app/.runtime/logs/.ci-write'

@@ -68,7 +68,9 @@ updates:
          - patch

  - package-ecosystem: docker
-    directory: /deploy
+    directories:
+      - /deploy
+      - /.github/actions/cargo-cache
    labels: []
    schedule:
      interval: weekly
@@ -1,4 +1,4 @@
-name: Reusable Container
+name: Container

 on:
  workflow_call:
@@ -30,30 +30,25 @@ jobs:
        id: buildx
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

-      - name: Cache Cargo mounts
+      - name: Restore Cargo snapshot
        id: cargo-cache
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        uses: actions/cache/restore@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 }}
+          # 同一平台和依赖复用快照，源码变化由 Cargo 指纹判定是否重编译
+          key: container-cargo-v3-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml', 'deploy/Dockerfile', '.github/actions/cargo-cache/Dockerfile') }}
          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 }}-
+            container-cargo-v3-${{ runner.os }}-${{ runner.arch }}-
+            container-cargo-v2-${{ 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
+        id: cargo-restore
+        uses: ./.github/actions/cargo-cache
        with:
+          operation: restore
          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 }}
+          path: ${{ runner.temp }}/container-cargo
+          architecture: amd64

      - name: Build runtime image
        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
@@ -67,7 +62,7 @@ jobs:
            runtime-base
            runtime
          cache-from: type=gha,scope=runtime-ci
-          cache-to: type=gha,mode=max,scope=runtime-ci
+          cache-to: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && 'type=gha,mode=max,scope=runtime-ci' || '' }}

      - name: Verify runtime image
        uses: ./.github/actions/verify-container
@@ -75,3 +70,23 @@ jobs:
          image: ${{ env.CPR_IMAGE }}
          platform: linux/amd64
          artifact-name: container-diagnostics-${{ github.run_id }}-${{ github.run_attempt }}-amd64
+
+      # 构建层命中时 mount 仍可能为空，只有实际检查过内容的快照才允许保存。
+      - name: Export Cargo snapshot
+        if: >-
+          github.event_name == 'push' && github.ref == 'refs/heads/main' &&
+          (steps.cargo-cache.outputs.cache-hit != 'true' || steps.cargo-restore.outputs.usable != 'true')
+        id: cargo-snapshot
+        uses: ./.github/actions/cargo-cache
+        with:
+          operation: snapshot
+          builder: ${{ steps.buildx.outputs.name }}
+          path: ${{ runner.temp }}/container-cargo
+          architecture: amd64
+
+      - name: Save Cargo snapshot
+        if: steps.cargo-snapshot.outputs.usable == 'true' && steps.cargo-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ${{ runner.temp }}/container-cargo
+          key: ${{ steps.cargo-cache.outputs.cache-primary-key }}
@@ -1,4 +1,4 @@
-name: Reusable Quality
+name: Quality

 on:
  workflow_call:
@@ -7,11 +7,6 @@ on:
        description: Exact commit SHA to validate
        required: true
        type: string
-      upload_frontend:
-        description: Upload the built frontend for release jobs
-        required: false
-        default: false
-        type: boolean
      run_backend:
        description: Run backend quality checks
        required: false
@@ -111,6 +106,7 @@ jobs:
        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
        with:
          workspaces: backend -> target
+          save-if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}

      - name: Rust format
        working-directory: backend
@@ -120,6 +116,19 @@ jobs:
        working-directory: backend
        run: cargo clippy --all-targets --all-features --locked -- -D warnings

+      - name: Setup nextest
+        uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21
+        with:
+          tool: cargo-nextest@0.9.143
+          fallback: none
+
+      - name: Build Rust tests once
+        working-directory: backend
+        run: |
+          cargo metadata --format-version 1 --locked > "$RUNNER_TEMP/nextest-cargo-metadata.json"
+          cargo nextest list --test main --locked --list-type binaries-only --message-format json \
+            > "$RUNNER_TEMP/nextest-binaries.json"
+
      - name: Configure PostgreSQL and Redis test authentication
        shell: bash
        run: |
@@ -144,7 +153,30 @@ jobs:

      - name: Rust tests
        working-directory: backend
-        run: cargo test --test main --locked
+        run: |
+          cargo nextest run \
+            --cargo-metadata "$RUNNER_TEMP/nextest-cargo-metadata.json" \
+            --binaries-metadata "$RUNNER_TEMP/nextest-binaries.json" \
+            --no-tests fail
+
+      - name: Store tests with Redis ACL authentication
+        working-directory: backend
+        shell: bash
+        run: |
+          set -euo pipefail
+          redis_acl_password="$(openssl rand -hex 24)"
+          echo "::add-mask::$redis_acl_password"
+          docker exec "${{ job.services.redis.id }}" redis-cli -e --no-auth-warning \
+            -u "$CPR_TEST_REDIS_URL" --user default ACL SETUSER cpr_acl reset on \
+            ">$redis_acl_password" '~*' '&*' '+@all' >/dev/null
+          docker exec --env REDISCLI_AUTH="$redis_acl_password" "${{ job.services.redis.id }}" \
+            redis-cli -e --user cpr_acl ACL SETUSER default off >/dev/null
+          export CPR_TEST_REDIS_URL="redis://cpr_acl:${redis_acl_password}@127.0.0.1:6379"
+          # 从同一份构建清单选择 Redis 测试，保留 workspace 特性图且不重复运行 PostgreSQL
+          cargo nextest run \
+            --cargo-metadata "$RUNNER_TEMP/nextest-cargo-metadata.json" \
+            --binaries-metadata "$RUNNER_TEMP/nextest-binaries.json" \
+            --no-tests fail -E 'package(=gateway-store) & test(/^redis::/)'

  frontend:
    if: inputs.run_frontend
@@ -158,35 +190,8 @@ jobs:
        with:
          ref: ${{ inputs.ref }}

-      - 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
-          cache: pnpm
-          cache-dependency-path: frontend/pnpm-lock.yaml
-
-      - name: Install frontend dependencies
-        run: pnpm --dir frontend install --frozen-lockfile
-
-      - name: Frontend format
-        run: pnpm --dir frontend format:check
-
-      - name: Frontend build
-        run: pnpm --dir frontend build
-
-      - name: Upload frontend artifact
-        if: inputs.upload_frontend
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: frontend-dist
-          path: frontend/dist
-          if-no-files-found: error
-          retention-days: 1
+      - name: Validate and build frontend
+        uses: ./.github/actions/build-frontend

  workflow-lint:
    runs-on: ubuntu-latest
@@ -206,5 +211,8 @@ jobs:
          -color
          .github/workflows/*.yml

-      - name: Check release script syntax
-        run: bash -n release/publish
+      - name: Check workflow script syntax
+        run: |
+          bash -n release/publish
+          shopt -s globstar nullglob
+          for script in .github/**/*.sh; do bash -n "$script"; done
@@ -38,14 +38,21 @@ jobs:
        id: filter
        uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
        with:
+          # 目录规则取并集，再统一排除说明文档，保留隐藏配置与子模块指针
+          predicate-quantifier: some-with-excludes
          filters: |
            backend:
              - 'backend/**'
              - 'release/version.yaml'
-              - '.github/workflows/**'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/_quality.yml'
+              - '!**/*.md'
            frontend:
              - 'frontend/**'
-              - '.github/workflows/**'
+              - '.github/actions/build-frontend/**'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/_quality.yml'
+              - '!**/*.md'
            source:
              - '.gitmodules'
              - 'modules/ui'
@@ -53,15 +60,18 @@ jobs:
              - 'frontend/**'
              - 'backend/crates/gateway-plugin/sdk/**'
              - '.github/workflows/ci.yml'
+              - '!**/*.md'
            container:
              - 'backend/**'
              - 'frontend/**'
              - 'deploy/**'
              - '.dockerignore'
              - 'release/version.yaml'
-              - '.github/actions/**'
+              - '.github/actions/verify-container/**'
+              - '.github/actions/cargo-cache/**'
              - '.github/workflows/_container.yml'
              - '.github/workflows/ci.yml'
+              - '!**/*.md'

  quality:
    needs: changes
@@ -165,12 +165,62 @@ jobs:
          puts "build_type=#{version.split("+", 2).first.include?("-exp.") ? "experimental" : "release"}"
          RUBY

+      - name: Seal plugin release manifest
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          GIT_SHA: ${{ steps.version.outputs.git_sha }}
+        run: |
+          ruby <<'RUBY'
+          require "fileutils"
+          require "json"
+
+          host_path = "backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json"
+          host = JSON.parse(File.read(host_path))
+          abort "Invalid plugin host compatibility declaration: #{host_path}" unless host["schema_version"] == 2
+          # 清单只依赖版本与兼容声明，平台归档和镜像消费同一份封口结果。
+          manifest = {
+            "schema_version" => 1,
+            "sealed" => true,
+            "gateway_version" => ENV.fetch("VERSION"),
+            "gateway_git_sha" => ENV.fetch("GIT_SHA"),
+            "plugin_host" => host,
+            "plugins" => [],
+          }
+          FileUtils.mkdir_p("dist/plugin-release-assets")
+          File.write("dist/plugin-release-assets/plugin-release-manifest.json", JSON.pretty_generate(manifest) + "\n")
+          RUBY
+
+      - name: Upload sealed plugin assets
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: plugin-release-assets
+          path: dist/plugin-release-assets
+          if-no-files-found: error
+          retention-days: 1
+
  quality:
    needs: [release-info]
    uses: ./.github/workflows/_quality.yml
    with:
      ref: ${{ needs.release-info.outputs.git_sha }}
-      upload_frontend: true
+      run_frontend: false
+
+  frontend:
+    needs: release-info
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    env:
+      CI: 'true'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release-info.outputs.git_sha }}
+
+      - name: Validate and build frontend
+        uses: ./.github/actions/build-frontend
+        with:
+          upload-artifact: 'true'

  build-docker-binary:
    name: build-docker-binary (${{ matrix.os }}-${{ matrix.arch }})
@@ -194,10 +244,10 @@ jobs:
            ~/.cargo/registry
            ~/.cargo/git
            backend/target
-          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 }}
+          # 按目标、工具链和依赖保存，不为每个发行提交复制整个 target
+          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml', '.github/workflows/release.yml') }}
          restore-keys: |
-            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 }}-
+            cargo-v3-${{ runner.os }}-${{ matrix.target }}-

      - name: Build binary
        shell: bash
@@ -260,10 +310,9 @@ jobs:
            ~/.cargo/registry
            ~/.cargo/git
            backend/target
-          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 }}
+          key: cargo-v3-${{ runner.os }}-${{ matrix.target }}-${{ hashFiles('backend/Cargo.lock', 'backend/rust-toolchain.toml', 'backend/**/Cargo.toml', 'backend/.cargo/config.toml', '.github/workflows/release.yml') }}
          restore-keys: |
-            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 }}-
+            cargo-v3-${{ runner.os }}-${{ matrix.target }}-

      - name: Build binary
        shell: bash
@@ -287,7 +336,7 @@ jobs:
          retention-days: 1

  package-assets:
-    needs: [release-info, quality, build-docker-binary, build-binary]
+    needs: [release-info, frontend, build-docker-binary, build-binary]
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
@@ -313,12 +362,17 @@ jobs:
          pattern: codex-proxy-rs-*
          path: dist/binaries

+      - name: Download sealed plugin assets
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: plugin-release-assets
+          path: dist/plugin-release-assets
+
      - name: Package release assets
        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
@@ -393,21 +447,8 @@ jobs:
                  raise SystemExit(f"Unsupported archive format: {platform['archive']}")
              release_packages.append((platform, package_root, archive_path))

-          plugin_host_path = pathlib.Path("backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json")
-          plugin_host = json.loads(plugin_host_path.read_text())
-          if plugin_host.get("schema_version") != 1:
-              raise SystemExit(f"Invalid plugin host compatibility declaration: {plugin_host_path}")
-
          plugin_manifest_path = release_dir / "plugin-release-manifest.json"
-          plugin_manifest_path.write_text(json.dumps({
-              "schema_version": 1,
-              "sealed": True,
-              "gateway_version": version,
-              "gateway_git_sha": os.environ["GIT_SHA"],
-              "plugin_host": plugin_host,
-              # 示例独立发版；当前不内置插件，仍保留更新与回滚所需的封口清单。
-              "plugins": [],
-          }, indent=2, sort_keys=True) + "\n")
+          shutil.copy2("dist/plugin-release-assets/plugin-release-manifest.json", plugin_manifest_path)
          assets.append(plugin_manifest_path)

          # 保留运行时清单目录合同，宿主包不再携带教学示例。
@@ -440,10 +481,12 @@ jobs:
          path: dist/release
          if-no-files-found: error
          retention-days: 1
+          # tar.gz 已压缩，Actions 只负责传递原始发行字节。
+          compression-level: 0

  build-docker-image:
    name: build-docker-image (${{ matrix.dockerPlatform }})
-    needs: [release-info, quality, build-docker-binary, package-assets]
+    needs: [release-info, frontend, build-docker-binary]
    strategy:
      fail-fast: false
      matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -476,11 +519,11 @@ 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
+      - name: Download sealed plugin assets
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
-          name: release-assets
-          path: dist/release-assets
+          name: plugin-release-assets
+          path: dist/plugin-release-assets

      - name: Prepare Docker prebuilt assets
        shell: bash
@@ -508,7 +551,7 @@ jobs:
          shutil.copy2(binary_src, binary_dest)
          binary_dest.chmod(0o755)

-          release_dir = pathlib.Path("dist/release-assets")
+          release_dir = pathlib.Path("dist/plugin-release-assets")
          manifest_path = release_dir / "plugin-release-manifest.json"
          manifest = json.loads(manifest_path.read_text())
          if manifest.get("schema_version") != 1 or manifest.get("sealed") is not True:
@@ -601,7 +644,8 @@ jobs:
          retention-days: 1

  publish:
-    needs: [release-info, package-assets, build-docker-image]
+    # 产物准备可与测试重叠，版本标签和 GitHub Release 必须等全部质量与镜像验证通过
+    needs: [release-info, quality, package-assets, build-docker-image]
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
@@ -1,4 +1,4 @@
-name: Agent Instructions Guard
+name: Rules Guard

 on:
  pull_request_target:
@@ -13,7 +13,7 @@ permissions:
  pull-requests: write

 concurrency:
-  group: agents-md-guard-${{ github.event.pull_request.number }}
+  group: rules-${{ github.event.pull_request.number }}
  cancel-in-progress: false

 jobs:
@@ -22,7 +22,7 @@ jobs:
    timeout-minutes: 5
    steps:
      # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
-      - name: Enforce agent instructions policy
+      - name: Check protected files
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        with:
          script: |
@@ -33,12 +33,15 @@ jobs:
              ...params,
              per_page: 100,
            });
-            const isInstructions = path => typeof path === 'string'
-              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md'));
+            const isProtectedRule = path => typeof path === 'string'
+              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md')
+                || path === 'CONTRIBUTING.md'
+                || path === '.agents/skills' || path.startsWith('.agents/skills/')
+                || path === '.github' || path.startsWith('.github/'));

            // 同时检查重命名前后的路径，避免通过移走规则文件绕过检查。
-            if (!files.some(file => isInstructions(file.filename) || isInstructions(file.previous_filename))) {
-              core.info('No agent instruction changes detected.');
+            if (!files.some(file => isProtectedRule(file.filename) || isProtectedRule(file.previous_filename))) {
+              core.info('No protected contribution rule changes detected.');
              return;
            }

@@ -49,27 +52,31 @@ jobs:
              return;
            }

+            // 通知标记保持稳定，以便复用机器人已有评论，避免重复提醒
            const marker = '<!-- agents-md-guard -->';
            const body = [
              marker,
-              '此 PR 修改了 `AGENTS.md`，已按贡献规则关闭。',
+              '佬友，我看到这个 PR 涉及受保护的协作规则文件，按仓库约定需要先关闭',
              '',
-              'PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。',
-              '请撤销相关变更后重新打开 PR；如需调整协作规则，请先提交 Issue 说明原因和建议，由维护者处理。',
+              '保护范围包括根目录或子目录的 `AGENTS.md`、根目录的 `CONTRIBUTING.md`，以及 `.agents/skills/` 和 `.github/` 中的所有文件，涵盖新增、修改、删除和重命名',
+              '',
+              '麻烦先撤销这些变更，再重新打开 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]'
+              const notification = comments.find(comment => comment.user?.login === 'github-actions[bot]'
                && comment.body?.includes(marker));
-              if (!notified) {
+              if (!notification) {
                await github.rest.issues.createComment({ owner, repo, issue_number: pr.number, body });
+              } else if (notification.body !== body) {
+                await github.rest.issues.updateComment({ owner, repo, comment_id: notification.id, 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.');
+            core.setFailed('Pull requests must not change protected contribution rules (AGENTS.md, CONTRIBUTING.md, .agents/skills/, .github/).');
@@ -1,4 +1,4 @@
-name: Security Scan
+name: Security

 on:
  push:
@@ -14,7 +14,7 @@ permissions:
  contents: read

 concurrency:
-  group: security-scan-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.head_ref || github.ref_name }}
+  group: security-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.head_ref || github.ref_name }}
  cancel-in-progress: true

 jobs:
@@ -27,20 +27,15 @@ jobs:
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

-      - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
-
-      - name: Cache Rust
-        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
+        uses: taiki-e/install-action@4cef1412cce204788f482e778a0b9187f9626a29 # v2.87.21
+        with:
+          tool: cargo-audit@0.22.2
+          fallback: none

      - name: Run Cargo audits
        run: |
-          cargo audit --file backend/Cargo.lock
+          cargo-audit audit --file backend/Cargo.lock

  frontend-security:
    runs-on: ubuntu-latest
@@ -6,7 +6,6 @@
 # Frontend
 /frontend/node_modules/
 /frontend/dist/
-/frontend/.vite/
 /frontend/.pnpm-store/
 /frontend/.pnpm-cache/
 *.tsbuildinfo
@@ -5,15 +5,21 @@
 | 任务意图与常见说法 | 必用技能 |
 | --- | --- |
 | 开发、实现、修复、排查报错、审查问题或代码、修改文档 | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md) |
-| 提交／提个 PR、准备或更新 PR、提交到已有 PR、看下 PR、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md)；需要修改时同时执行 cpr-dev-guide |
-| 提 Issue、反馈到仓库、把问题或建议整理成 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
+| 提交／提个 PR、准备或更新 PR、看下 PR、回复 PR 讨论、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md)；需要修改时同时执行 cpr-dev-guide |
+| 提 Issue、反馈到仓库、把问题或建议整理成 Issue、补充或回复 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
 | 写网关插件、修改插件能力、排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide |
 | 发版、准备版本、发布 beta／实验版、整理发布说明、打发行 tag | [cpr-release](.agents/skills/cpr-release/SKILL.md) |

-结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入。
-任务进入新阶段时补载对应技能，不能只读取文件而跳过其中的问题核实、自审、验证与交付步骤。协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)。
+结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入
+
+只加载当前任务命中的技能、模式和文档章节，复用已有上下文，进入新阶段再补读；链接是按需入口，不是全文或全部参考文件的必读清单
+
+执行所选流程中的问题核实、自审、验证与交付要求，协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Issue 和 PR 回复分别按对应技能的[Issue 回复口吻](.agents/skills/cpr-github-issue/SKILL.md#回复口吻)与[PR 回复口吻](.agents/skills/cpr-github-pr/SKILL.md#回复口吻)执行
+
 模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
-没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。
+没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则

 <!-- CODEGRAPH_START -->
 ## CodeGraph
@@ -28,11 +34,12 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is

 ## 工作方式

- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题；涉及 Codex 行为、协议或兼容性时，按[参考仓库优先级](.agents/skills/cpr-dev-guide/SKILL.md#参考仓库的优先级)以官方 Codex 仓库对应版本源码为第一手资料，三方仓库仅作参考
 - 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
 - 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。
 - 页面变更先复用已有页面设计与组件，不因个人偏好重排页面或另建交互。文案取舍遵循 [界面文案与信息层级](docs/theme.md#界面文案与信息层级)，页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
 - 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
+- 常规文档只描述当前状态，不记录变更历史；按[文档职责与更新条件](CONTRIBUTING.md#文档职责与更新条件)在所属章节就地修订，分清层次与详略，短段和列表少用句号，交付前逐段检查必要性、归属、重复与当前状态表达
 - 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
 - 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。
 - 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。
@@ -43,7 +50,7 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is
 ### 审查范围

 - 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。
- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。
+- 按[审查标准](CONTRIBUTING.md#审查标准)检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称
 - 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。
 - 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。

@@ -1,47 +1,47 @@
 # 贡献与审查

-贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
+贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理

-本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
+本文定义协作流程与审查标准；模块职责以 [系统架构](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) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏。
+按场景选择 [接口问题反馈](.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](.github/ISSUE_TEMPLATE/general-bug-report.yml) 或 [功能建议](.github/ISSUE_TEMPLATE/feature-request.yml) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏

-日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案。
+日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案

 ## 问题与方案依据

-开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
+开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题

-涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
+涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据

-官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
+官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案

-反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、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. **修改与合并。** 更新代码后重新执行受影响的检查，确认审查意见已处理，验证证据对应当前变更。维护者审阅批准后再合并；需要升级说明的变更同步相关文档。
+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 #编号”时，应按下列标准执行，无需再次列举要求。
+AI 开发和审查入口是根目录的 [AGENTS.md](AGENTS.md)。在仓库上下文中要求“审查 PR #编号”时，应按下列标准执行，无需再次列举要求

 ### 项目技能

 仓库技能位于 `.agents/skills/`，随代码共享。技能提供执行流程，协作与审查标准仍以本文和 `AGENTS.md` 为准。
-AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证。
+AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；准备、创建、更新及审查 PR 必须执行 `cpr-github-pr`，不以用户是否显式点名技能为条件。PR 内修复仍须经过开发流程，不能用填写 PR 正文代替实现自审与验证

 | 技能 | 用途 | 调用示例 |
 | --- | --- | --- |
@@ -51,26 +51,33 @@ AI 开发、排查、代码审查和文档修改必须执行 `cpr-dev-guide`；
 | [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 自动审查。
+审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查

 ### AI 使用披露

 PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。
 `Codex`、`ChatGPT`、`Claude Code` 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。
 无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。
-更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定。
+更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定

 ### 规则文件保护

-PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。
+PR 不接受以下协作规则文件的新增、修改、删除或重命名：

-源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。
+- 根目录及任意子目录的 `AGENTS.md`
+- 根目录的 `CONTRIBUTING.md`
+- `.agents/skills/` 中的所有文件，包括技能入口、引用文档、配置和脚本
+- `.github/` 中的所有文件，包括工作流、Actions、Issue／PR 模板和依赖更新配置
+
+调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/rules.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查
+
+源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流

 ## 审查标准

-按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。
+按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告

-结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。
+结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证

 | 维度 | 检查重点 |
 | --- | --- |
@@ -86,59 +93,81 @@ PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或

 审查意见区分三类：

- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向。
- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构。
- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷。
+- **必须修复：** 有具体触发条件的缺陷、违反现有合同或明确项目规范的问题。说明位置、依据、影响和最小修复方向
+- **建议：** 不影响合同或规范的替代实现、命名偏好和局部优化。个人偏好不能单独阻止合并，也不应强求与本次目标无关的重构
+- **验证缺口：** 尚未检查的行为、状态或运行环境。说明缺少什么证据，由维护者评估是否需要补齐，不能把未验证当作已通过或已发现缺陷

-复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则。
+复杂度不按行数判断，复用不只看语法相似。建议合并重复逻辑时应指出共享的业务含义；建议保留特殊分支时应能说明它服务的场景。例外应有依据，不能仅为绕过检查而放宽规则

 ## 项目约定

- 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 聚焦目标；无关格式化、重构和依赖升级单独处理。
+- 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 自动追加发布说明。
- 仍影响实际升级、恢复或兼容使用的限制与操作应保留，并注明适用条件；不能仅因涉及旧版就删除。
-  审查文档改动时核对必要性、所属职责与重复内容，区分当前使用说明和仅解释此次修复的内容。
+只有用法、合同、职责、约束或读者需要执行的操作发生变化时才更新，内部重构和界面微调不默认附带文档改动
+
+### 内容归属
+
+| 文档 | 回答的问题 | 详略边界 |
+| --- | --- | --- |
+| [README](README.md) | 项目能做什么，如何开始 | 简短介绍、最短可用路径和文档导航 |
+| [部署与运维](deploy/README.md) | 如何安装、接入、排障和恢复 | 前置条件、配置、操作步骤、结果判断与风险 |
+| [开发与源码联调](docs/development.md) | 如何准备环境、运行源码和联调独立仓库 | 可执行命令、目录关系和依赖维护 |
+| [API 参考](docs/api.md) | 调用者如何正确请求和解释结果 | 鉴权、字段、默认值、错误、限制与幂等语义，不展开内部实现或界面布局 |
+| [系统架构](docs/architecture.md) | 业务事实归谁，调用如何协作 | 模块边界、状态所有权、生命周期和不变量，不重复字段清单 |
+| [管理端主题](docs/theme.md) | 界面如何保持一致，主题如何扩展 | 文案与视觉约束、Token 合同、实现入口和验收范围 |
+| [插件使用](docs/plugins.md) | 如何安装、授权、配置和使用插件 | 管理员操作与影响，不展开 SDK 调用或宿主事务实现 |
+| [插件 SDK](backend/crates/gateway-plugin/sdk/README.md) / [CLI](backend/apps/plugin-cli/README.md) | 如何编写和打包插件 | 作者合同、权限边界、示例与打包验证 |
+| [数据库迁移](backend/migrations/README.md) | 如何维护 schema 和准备测试库 | 冻结规则、升级约束和测试环境，不罗列迁移历史 |
+| 本文 | 如何协作、审查和交付 | 流程、判断标准与验证要求，任务入口由 [开发技能](.agents/skills/cpr-dev-guide/SKILL.md) 串联 |
+
+- 同一事实只在所属文档完整说明，其他位置按读者任务保留必要摘要和链接
+- 改动原因、前后对比、排查经过和验证结果放在 PR、Issue 或任务报告；`release/notes.md` 是发版时使用的发布说明，不作为常规文档的历史章节，也不随普通开发任务自动追加
+- 仍影响升级、恢复或兼容使用的内容，写成明确的适用条件与操作，保留必要限制，不叙述演变过程
+
+### 层次与行文
+
+- 按读者任务组织章节，先给入口和操作，再解释限制；长篇参考文档提供导航，独立主题使用小标题
+- 快速开始只保留走通流程的必要步骤；API、配置、恢复和权限等容易误用的内容写清输入、默认值、边界与失败处理
+- 短说明直接成段，并列信息用列表，可比较的字段或职责用表格，避免一段堆叠多个主题
+- 标题、表格单元格、短列表项和独立短段通常不加句号；长段优先拆分，确需区分完整句意时保留句号，不机械替换成逗号或分号
+- 命令、URL、版本号、字段名和原始输出保持准确，不为统一标点改写代码示例
+
+审查时逐段核对：是否属于当前状态、是否回答读者问题、是否放在正确文档、是否重复、脱离变更背景能否独立理解
+
+没有文档改动本身不构成验证缺口，判断依据是当前说明是否仍然准确、完整

 ## 界面验证

-AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由。
+AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有页面为依据，优先延续原页面的布局、信息层级与交互；设计技能不构成重做页面的理由

-开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题

-列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
+列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令

 提交者在浏览器中验证受影响路径，页面变更的 PR 必须提供实际运行截图，包括布局、文案、样式和交互状态的变化：

- 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件。
- 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面。
- 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件。
- 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果。
- 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并。
+- 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件
+- 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面
+- 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件
+- 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果
+- 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并

-截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确。
+截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确

-涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
+涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收

 ## 验证

-选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
+选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言

 | 范围 | 现有检查 | 仍需提供的证据 |
 | --- | --- | --- |
@@ -148,15 +177,9 @@ AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方
 | 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
 | 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |

-UI 与示例源码分别在独立的 `codex-proxy-ui`、`codex-proxy-plugins` 仓库维护。前端的依赖、锁文件和 ESLint 配置均在 `frontend/` 管理，仓库根目录不维护 Node 包。UI 使用固定 GitHub 标签或提交依赖，锁文件记录实际提交、源码归档地址及完整性摘要，常规开发和 CI 不需要检出同级仓库。安装时 pnpm 按 UI 自身锁文件准备构建依赖，再执行 `prepack` 生成 JS、CSS 和类型声明。开发服务通过 UI 包的 `development` 入口使用 Vue SFC，生产构建使用 `dist`。
+环境准备、依赖安装和服务启动见 [开发与源码联调](docs/development.md)，联合修改组件库或插件时使用其中的子模块入口

-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 提交，不依赖浮动分支。
+正式依赖固定到标签或提交，联调只临时替换解析路径，不改写正式依赖或锁文件

 前端从仓库根目录执行：

@@ -166,16 +189,20 @@ pnpm --dir frontend build
 git diff --check
 ```

-`build` 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 [修改与验收](docs/architecture.md#12-修改与验收)。
+`build` 已包含类型检查；不维护独立前端测试代码。后端的工具链、命令与线程栈设置统一见 [修改与验收](docs/architecture.md#12-修改与验收)

-依赖 PostgreSQL / Redis 的测试使用 [专用测试环境](backend/migrations/README.md#本地测试库)，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 [质量工作流](.github/workflows/_quality.yml) 与 [安全扫描](.github/workflows/security-scan.yml)。
+依赖 PostgreSQL / Redis 的测试使用 [专用测试环境](backend/migrations/README.md#本地测试库)，未配置导致跳过时明确记录。CI 中已有对应服务和检查，见 [质量工作流](.github/workflows/_quality.yml) 与 [安全扫描](.github/workflows/security.yml)

-集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论。
+集成变更应验证实际业务路径及结果，不能只凭健康检查或探测成功认定全链路正常。协议和网络改动按需核对认证、证书、代理、流式交付及客户端结果；记录影响复现的环境条件。缺少运行条件时说明缺口，不用模拟结果代替真实集成结论

 ## 自动检查与合并条件

-[CI](.github/workflows/ci.yml) 已按变更范围调用现有质量检查。新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试。
+[CI](.github/workflows/ci.yml) 按变更范围调用质量检查，Markdown 不触发后端、前端、容器和源码联调任务，工作流语法检查独立执行

-AI 自动审查需要在所用工具中单独启用。其支持的检查范围和优先级过滤以工具说明为准；即使能读取 `AGENTS.md`，也不能保证所有可维护性和视觉问题都会被报告。配置参考 [Codex GitHub 审查文档](https://learn.chatgpt.com/docs/third-party/github)。
+后端 CI 使用 nextest 执行 `main` 集成测试，默认 Redis 密码模式执行完整测试集，ACL 用户模式复用同一批构建产物执行 Store 的 Redis 测试；本地验证命令见 [架构文档](docs/architecture.md#验证命令)

-要由 GitHub 强制执行合并条件，维护者需配置对应分支的必需状态检查、审阅批准和讨论解决要求，并按需要设置新提交后的重新审阅。配置前核对实际检查名称与触发范围，见 [GitHub 分支保护](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)。规则文档本身不会启用 AI 服务或更改分支设置。
+新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试
+
+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 服务或更改分支设置
@@ -21,7 +21,7 @@

 ## 快速预览

-无需部署，打开 [快速预览服务](https://codex-proxy-rs.ainz.cc) 即可体验管理端的系统概览、账号分组、代理管理与用量统计
+无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计：

 | 登录信息 | 默认值 |
 | --- | --- |
@@ -30,14 +30,17 @@
 | 账号 | `admin@cpr.local` |
 | 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |

-预览服务运行已发布版本，展示的账号、代理与使用记录均为模拟数据，每天北京时间 `00:00` 自动生成当天数据。
+预览服务运行已发布版本，展示的账号、代理与使用记录均为模拟数据，每天北京时间 `00:00` 自动生成当天数据
+
 这是公开共享的功能预览环境，不提供真实模型调用；请勿导入真实账号、密钥或其他敏感信息

 ## 快速开始

-使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis。
-以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
-[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置
+使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis
+
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL
+
+已有部署请先看 [升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置

 ### 一键安装

@@ -48,8 +51,9 @@ curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/in
 ```

 [安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`，下载同一正式 Release 的部署文件，
-自动生成密码、设置目录权限并启动服务。完成后会显示访问地址和管理员密码，请保存密码，再按下方步骤
-[添加账号与客户端密钥](#添加账号与客户端密钥)
+自动生成密码、设置目录权限并启动服务
+
+完成后保存显示的访问地址和管理员密码，再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)

 可在执行 `bash install.sh` 时传入环境变量：

@@ -65,7 +69,7 @@ curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/in
 INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
 ```

-重复运行时请使用同一安装目录。检测到 `deploy/config.yaml` 后，脚本保留现有配置和部署文件，
+重复运行时请使用同一安装目录，检测到 `deploy/config.yaml` 后，脚本保留现有配置和部署文件，
 忽略传入的管理员密码，也不执行版本升级

 ### 手动安装
@@ -74,9 +78,9 @@ INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh

 ### 登录管理端

-部署完成后，打开 `http://127.0.0.1:8080`，使用 `admin@cpr.local` 和管理员密码登录。
-API Key 持有者可在同一登录页切换登录身份，进入 `/key-usage` 查看自己的用量、趋势、请求日志、额度与健康时间线；不能访问管理员页面。
-页面右上角的「密钥配置」支持复制 Codex 配置文件和导入 CCSwitch，导入时同时启用当前 Key 的日／周额度查询，默认刷新间隔为 30 分钟
+部署完成后，打开 `http://127.0.0.1:8080`，使用 `admin@cpr.local` 和管理员密码登录
+
+API Key 持有者可在登录页切换身份，查看自己的用量与额度，并通过「密钥配置」复制 Codex 配置或导入 CCSwitch

 默认地址只能在服务器本机访问，从其他设备使用时，需要配置
 [HTTPS 反向代理](deploy/README.md#公网访问)
@@ -89,8 +93,9 @@ API Key 持有者可在同一登录页切换登录身份，进入 `/key-usage`

 ## 客户端接入

-**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入。
-合并到客户端配置后重启 Codex。完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
+**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入，合并配置后重启 Codex
+
+完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)

 **其他 Responses API 客户端**：填写以下信息：

@@ -114,7 +119,8 @@ curl http://127.0.0.1:8080/v1/models \
 | 接口集成 | [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) |
+| 开发宿主 | [开发与源码联调](docs/development.md) · [系统架构](docs/architecture.md) · [管理端主题](docs/theme.md) · [数据库迁移](backend/migrations/README.md) |
+| 参与协作 | [贡献、审查与验证](CONTRIBUTING.md) |

 ## 社区

@@ -31,6 +31,12 @@ dependencies = [
 "memchr",
 ]

+[[package]]
+name = "allocation-counter"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "beb9e990c0a33699f1984d85a6abead615ccc72dd8130bf3e15dcabe2ca149c9"
+
 [[package]]
 name = "allocator-api2"
 version = "0.2.21"
@@ -242,9 +248,9 @@ dependencies = [

 [[package]]
 name = "aws-runtime"
-version = "1.9.4"
+version = "1.10.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "25b43ad47adc2517efe3d706559d94b97e50e80e0321b3cadbc9f77cee88adcd"
+checksum = "2b8a9911551b4ea6ca13805ef52ed96f7d2bbb43cc3b4a14cb0776a71f33cfaa"
 dependencies = [
 "aws-credential-types",
 "aws-sigv4",
@@ -258,10 +264,8 @@ dependencies = [
 "bytes",
 "bytes-utils",
 "fastrand",
- "http 0.2.12",
- "http 1.5.0",
- "http-body 0.4.6",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "percent-encoding",
 "pin-project-lite",
 "tracing",
@@ -270,9 +274,9 @@ dependencies = [

 [[package]]
 name = "aws-sdk-s3"
-version = "1.148.0"
+version = "1.152.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8a61c1db3987ab6c8740fb87f248864687d50549401115244a84f02c3047b2d5"
+checksum = "004d5acbd6850ab58789a43822e0a2ef23927a46b012c17f8fa51253103db9f8"
 dependencies = [
 "arc-swap",
 "aws-credential-types",
@@ -294,22 +298,21 @@ dependencies = [
 "fastrand",
 "hex",
 "hmac",
- "http 0.2.12",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "lru",
 "percent-encoding",
 "regex-lite",
- "sha2 0.11.0",
+ "sha2",
 "tracing",
 "url",
 ]

 [[package]]
 name = "aws-sigv4"
-version = "1.5.3"
+version = "1.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "31d955e76ff96acd555bf06fa0fa6d5bf9335fa84ae7c64481b20ae61d231f70"
+checksum = "2312577f088c9fbf4206dfdb884cf1de9407b43e1a923cbed5237775116fc24b"
 dependencies = [
 "aws-credential-types",
 "aws-smithy-eventstream",
@@ -320,10 +323,9 @@ dependencies = [
 "form_urlencoded",
 "hex",
 "hmac",
- "http 0.2.12",
- "http 1.5.0",
+ "http",
 "percent-encoding",
- "sha2 0.11.0",
+ "sha2",
 "time",
 "tracing",
 ]
@@ -350,13 +352,13 @@ dependencies = [
 "bytes",
 "crc-fast",
 "hex",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "md-5",
 "pin-project-lite",
 "sha1 0.11.0",
- "sha2 0.11.0",
+ "sha2",
 "tracing",
 ]

@@ -373,9 +375,9 @@ dependencies = [

 [[package]]
 name = "aws-smithy-http"
-version = "0.64.0"
+version = "0.64.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37843d9add67c3aff5856f409c6dc315d3cdff60f9c0cb5b670dab1e9920306d"
+checksum = "639b4d8f8555f24a9be649811c3eb0b4d4616f4d61daf0c32e28873bc1ea9af1"
 dependencies = [
 "aws-smithy-eventstream",
 "aws-smithy-runtime-api",
@@ -384,8 +386,8 @@ dependencies = [
 "bytes-utils",
 "futures-core",
 "futures-util",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "percent-encoding",
 "pin-project-lite",
@@ -395,15 +397,15 @@ dependencies = [

 [[package]]
 name = "aws-smithy-http-client"
-version = "1.4.2"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7bd25384a4e437aa8d8f339afad4b69e786b936a7cb10db668a7aaf66717b1a8"
+checksum = "51c89cc3f1f281d659a67a519a1b5c6d445b5ce09fa7e5aee40c2c2707e9509d"
 dependencies = [
 "aws-smithy-async",
 "aws-smithy-runtime-api",
 "aws-smithy-types",
 "h2",
- "http 1.5.0",
+ "http",
 "hyper",
 "hyper-rustls",
 "hyper-util",
@@ -439,9 +441,9 @@ dependencies = [

 [[package]]
 name = "aws-smithy-runtime"
-version = "1.14.2"
+version = "1.16.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3296253d3a91b3f938a3f2bcce4daebadcb4aa4228153fcec90f9d23532b4484"
+checksum = "d6e302ac1d88b99652489df31abdec6ac42a2ab2ac3982ad0ac49f64dfaf28ba"
 dependencies = [
 "aws-smithy-async",
 "aws-smithy-http",
@@ -452,10 +454,8 @@ dependencies = [
 "aws-smithy-types",
 "bytes",
 "fastrand",
- "http 0.2.12",
- "http 1.5.0",
- "http-body 0.4.6",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "pin-project-lite",
 "pin-utils",
@@ -465,16 +465,15 @@ dependencies = [

 [[package]]
 name = "aws-smithy-runtime-api"
-version = "1.16.2"
+version = "1.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6d881a7b7ad179fd6611680c9de89f716fb00ab40299a9a7b8c6913e8f7511a8"
+checksum = "c0730c16f91124c6a2abb4932c77e299288b3dd9f967ea2e9ec48cc6731e87a4"
 dependencies = [
 "aws-smithy-async",
 "aws-smithy-runtime-api-macros",
 "aws-smithy-types",
 "bytes",
- "http 0.2.12",
- "http 1.5.0",
+ "http",
 "pin-project-lite",
 "tokio",
 "tracing",
@@ -500,23 +499,21 @@ checksum = "e8f395d93304280b64b7632fea798d177e74897fe7f063416ce627cd6fa24829"
 dependencies = [
 "aws-smithy-runtime-api",
 "aws-smithy-types",
- "http 1.5.0",
+ "http",
 ]

 [[package]]
 name = "aws-smithy-types"
-version = "1.6.4"
+version = "1.8.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b791f3ac597193fe1d08b82366986eb1f5bc31f2ac6c194c0855276116c76cd"
+checksum = "69bb407740a197147da48238ecc94498493c9e85445732360cec180296ca45f1"
 dependencies = [
 "base64-simd",
 "bytes",
 "bytes-utils",
 "futures-core",
- "http 0.2.12",
- "http 1.5.0",
- "http-body 0.4.6",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "itoa",
 "num-integer",
@@ -567,8 +564,8 @@ dependencies = [
 "bytes",
 "form_urlencoded",
 "futures-util",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "hyper",
 "hyper-util",
@@ -576,6 +573,7 @@ dependencies = [
 "matchit",
 "memchr",
 "mime",
+ "multer",
 "percent-encoding",
 "pin-project-lite",
 "serde_core",
@@ -599,8 +597,8 @@ checksum = "08c78f31d7b1291f7ee735c1c6780ccde7785daae9a9206026862dab7d8792d1"
 dependencies = [
 "bytes",
 "futures-core",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "mime",
 "pin-project-lite",
@@ -879,7 +877,7 @@ dependencies = [
 "gateway-plugin-sdk",
 "hex",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "tar",
 "tempfile",
 "thiserror",
@@ -935,9 +933,9 @@ dependencies = [

 [[package]]
 name = "config"
-version = "0.15.25"
+version = "0.15.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b85f248a4de22d204ceabc6299d89d2c70fbd7f09fea53c06c852369652d8139"
+checksum = "38e9fbc53afcec54441422f1c596cd054655b32e70e1cbac956651b7b175a404"
 dependencies = [
 "pathdiff",
 "serde_core",
@@ -1683,13 +1681,17 @@ dependencies = [
 "gateway-core",
 "heck",
 "hex",
+ "hkdf",
+ "prettyplease",
+ "quote",
 "rand_core 0.6.4",
 "secrecy",
 "semver",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "subtle",
+ "syn 3.0.6",
 "tempfile",
 "thiserror",
 "tokio",
@@ -1712,10 +1714,13 @@ dependencies = [
 "gateway-core",
 "gateway-protocol",
 "headers",
+ "http",
+ "http-body",
+ "http-body-util",
 "secrecy",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "thiserror",
 "tokio",
 "tokio-tungstenite 0.29.0",
@@ -1731,16 +1736,21 @@ dependencies = [
 name = "gateway-core"
 version = "0.1.0"
 dependencies = [
+ "allocation-counter",
 "async-trait",
 "base64 0.23.1",
 "bytes",
+ "chrono",
 "chrono-tz",
+ "event-listener",
 "futures",
 "futures-timer",
+ "http",
+ "http-body-util",
 "semver",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "thiserror",
 "tracing",
 "url",
@@ -1763,7 +1773,7 @@ dependencies = [
 "gateway-admin",
 "gateway-core",
 "hex",
- "http 1.5.0",
+ "http",
 "http-body-util",
 "hyper",
 "hyper-rustls",
@@ -1779,12 +1789,14 @@ dependencies = [
 "serde",
 "serde_ignored",
 "serde_json",
- "sha2 0.11.0",
+ "serde_path_to_error",
+ "sha2",
 "tar",
 "tempfile",
 "thiserror",
 "tokio",
 "tokio-rustls",
+ "tokio-tungstenite 0.29.0",
 "tower-service",
 "tracing",
 "tracing-appender",
@@ -1809,6 +1821,9 @@ dependencies = [
 "gateway-protocol",
 "gateway-store",
 "hex",
+ "http",
+ "http-body",
+ "http-body-util",
 "image",
 "jsonschema",
 "roxmltree",
@@ -1816,12 +1831,13 @@ dependencies = [
 "semver",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "sqlx",
 "tar",
 "tempfile",
 "thiserror",
 "tokio",
+ "tokio-tungstenite 0.29.0",
 "tracing",
 "url",
 "uuid",
@@ -1843,6 +1859,9 @@ dependencies = [
 name = "gateway-protocol"
 version = "0.0.0"
 dependencies = [
+ "http",
+ "httpdate",
+ "memchr",
 "serde",
 "serde_json",
 "thiserror",
@@ -1869,7 +1888,7 @@ dependencies = [
 "secrecy",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "sqlx",
 "tempfile",
 "thiserror",
@@ -1962,16 +1981,16 @@ dependencies = [

 [[package]]
 name = "h2"
-version = "0.4.16"
+version = "0.4.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a9f37a958b41b3b19ee2707c06439c0e9e547e847223eb791ecb0cb821c65e27"
+checksum = "7d29020232d6aa3fb1daca64c1127cf662cf97f254ae16c18c05b8ab635fc118"
 dependencies = [
 "atomic-waker",
 "bytes",
 "fnv",
 "futures-core",
 "futures-sink",
- "http 1.5.0",
+ "http",
 "indexmap",
 "slab",
 "tokio",
@@ -2012,14 +2031,14 @@ dependencies = [

 [[package]]
 name = "headers"
-version = "0.4.1"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b3314d5adb5d94bcdf56771f2e50dbbc80bb4bdf88967526706205ac9eff24eb"
+checksum = "fc2700e3fe555c3310aa7286cac6167449f2c87e0eb58769c9208a1c58a1d106"
 dependencies = [
 "base64 0.22.1",
 "bytes",
 "headers-core",
- "http 1.5.0",
+ "http",
 "httpdate",
 "mime",
 "sha1 0.10.7",
@@ -2031,7 +2050,7 @@ version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "54b4a22553d4242c49fddb9ba998a99962b5cc6f22cb5a3482bec22522403ce4"
 dependencies = [
- "http 1.5.0",
+ "http",
 ]

 [[package]]
@@ -2080,17 +2099,6 @@ dependencies = [
 "markup5ever",
 ]

-[[package]]
-name = "http"
-version = "0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "601cbb57e577e2f5ef5be8e7b83f0f63994f25aa94d673e54a92d5c516d101f1"
-dependencies = [
- "bytes",
- "fnv",
- "itoa",
-]
-
 [[package]]
 name = "http"
 version = "1.5.0"
@@ -2103,23 +2111,12 @@ dependencies = [

 [[package]]
 name = "http-body"
-version = "0.4.6"
+version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7ceab25649e9960c0311ea418d17bee82c0dcec1bd053b5f9a66e265a693bed2"
+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"
 dependencies = [
 "bytes",
- "http 0.2.12",
- "pin-project-lite",
-]
-
-[[package]]
-name = "http-body"
-version = "1.0.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
-dependencies = [
- "bytes",
- "http 1.5.0",
+ "http",
 ]

 [[package]]
@@ -2130,8 +2127,8 @@ checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c"
 dependencies = [
 "bytes",
 "futures-core",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "pin-project-lite",
 ]

@@ -2175,8 +2172,8 @@ dependencies = [
 "futures-channel",
 "futures-core",
 "h2",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "httparse",
 "httpdate",
 "itoa",
@@ -2192,7 +2189,7 @@ version = "0.27.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
 dependencies = [
- "http 1.5.0",
+ "http",
 "hyper",
 "hyper-util",
 "log",
@@ -2229,8 +2226,8 @@ dependencies = [
 "bytes",
 "futures-channel",
 "futures-util",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "hyper",
 "ipnet",
 "libc",
@@ -2450,9 +2447,9 @@ dependencies = [

 [[package]]
 name = "jsonschema"
-version = "0.56.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6a806f80c1f5560431009ce5ec29b59d38f950e0cd7db5f1b8925e6d8104e21"
+checksum = "f622c574a29fb3034a0a90645afee194dfedc75fc124228801b6e77041075bd1"
 dependencies = [
 "ahash",
 "bytecount",
@@ -2478,18 +2475,18 @@ dependencies = [

 [[package]]
 name = "jsonschema-regex"
-version = "0.56.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cb862addfa7782108933abcf842fe25334523a9df5b89ea4d9620e3dd7b42181"
+checksum = "a968fffd387b2ab005bf00c1851f5d26e90df05b6f7ad609ed0d620033cca5e7"
 dependencies = [
 "regex-syntax",
 ]

 [[package]]
 name = "jsonschema-value"
-version = "0.56.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a05cd404c5ff6e2731dbbf7e290a27417750acfb59e329560a1d0af384c93fb0"
+checksum = "39b7670345e5ce87371339d13705dbb9276b7e3e934bbe1efa2c6734a1f65a96"
 dependencies = [
 "ahash",
 "bytecount",
@@ -2529,6 +2526,15 @@ version = "0.2.186"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"

+[[package]]
+name = "libredox"
+version = "0.1.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "61ff90caf6077a803a240f62fdbe88645a890bbca49ef8174c3cb0404362171d"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "libsqlite3-sys"
 version = "0.37.0"
@@ -2703,6 +2709,23 @@ dependencies = [
 "pxfm",
 ]

+[[package]]
+name = "multer"
+version = "3.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "83e87776546dc87511aa5ee218730c92b666d7264ab6ed41f9d215af9cd5224b"
+dependencies = [
+ "bytes",
+ "encoding_rs",
+ "futures-util",
+ "http",
+ "httparse",
+ "memchr",
+ "mime",
+ "spin 0.9.9",
+ "version_check",
+]
+
 [[package]]
 name = "native-tls"
 version = "0.2.14"
@@ -2829,6 +2852,24 @@ dependencies = [
 "libc",
 ]

+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "objc2-system-configuration"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7216bd11cbda54ccabcab84d523dc93b858ec75ecfb3a7d89513fa22464da396"
+dependencies = [
+ "objc2-core-foundation",
+]
+
 [[package]]
 name = "once_cell"
 version = "1.21.4"
@@ -2917,7 +2958,7 @@ dependencies = [
 "elliptic-curve",
 "primefield",
 "primeorder",
- "sha2 0.11.0",
+ "sha2",
 ]

 [[package]]
@@ -3175,6 +3216,16 @@ version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "925383efa346730478fb4838dbe9137d2a47675ad789c546d150a6e1dd4ab31c"

+[[package]]
+name = "prettyplease"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2bfe0f4c752e450fc2faf62654f1c134747922825d5b04ca717b8874f41a40c0"
+dependencies = [
+ "proc-macro2",
+ "syn 3.0.6",
+]
+
 [[package]]
 name = "primefield"
 version = "0.14.0"
@@ -3215,6 +3266,7 @@ dependencies = [
 name = "provider-openai"
 version = "0.0.0"
 dependencies = [
+ "allocation-counter",
 "async-stream",
 "async-trait",
 "aws-lc-rs",
@@ -3230,6 +3282,7 @@ dependencies = [
 "gateway-core",
 "gateway-protocol",
 "getrandom 0.4.3",
+ "h2",
 "hex",
 "hyper",
 "hyper-rustls",
@@ -3237,6 +3290,7 @@ dependencies = [
 "native-tls",
 "openssl",
 "openssl-sys",
+ "regex",
 "reqwest",
 "roxmltree",
 "rustls",
@@ -3246,7 +3300,7 @@ dependencies = [
 "semver",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "subtle",
 "tar",
 "tempfile",
@@ -3288,7 +3342,7 @@ dependencies = [
 "semver",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "thiserror",
 "tokio",
 "tracing",
@@ -3348,9 +3402,9 @@ dependencies = [

 [[package]]
 name = "quinn-proto"
-version = "0.11.16"
+version = "0.11.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2f4bfc015262b9df63c8845072ce59068853ff5872180c2ce2f13038b970e560"
+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"
 dependencies = [
 "bytes",
 "getrandom 0.4.3",
@@ -3384,9 +3438,9 @@ dependencies = [

 [[package]]
 name = "quote"
-version = "1.0.46"
+version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
 "proc-macro2",
 ]
@@ -3478,9 +3532,9 @@ dependencies = [

 [[package]]
 name = "redis"
-version = "1.7.0"
+version = "1.7.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2acbc41a996f7652b2ddd9dfd98cc4ff602cfd742ae35382f07f608405ab50ed"
+checksum = "ed5b98ae99461e02895c3a96a25dbe4d852a3d5e5b815d31d5d9e4b5344d99e9"
 dependencies = [
 "arc-swap",
 "arcstr",
@@ -3534,9 +3588,9 @@ dependencies = [

 [[package]]
 name = "referencing"
-version = "0.56.0"
+version = "0.58.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a3b4a92fac7e28c27de3ad26df2ecb9e652f227b258e845af034052e5b22c96c"
+checksum = "558f3855529c0a7e78a48e409fa653456e55f1b167eab4109c16a255b7727e3f"
 dependencies = [
 "ahash",
 "fluent-uri",
@@ -3551,9 +3605,9 @@ dependencies = [

 [[package]]
 name = "regex"
-version = "1.13.0"
+version = "1.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2a0e75113e14dc5acb068cd0786884f214f1312650a3d36d269f5c4f3cdee8a2"
+checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d"
 dependencies = [
 "aho-corasick",
 "memchr",
@@ -3598,8 +3652,8 @@ dependencies = [
 "futures-core",
 "futures-util",
 "h2",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "hyper",
 "hyper-rustls",
@@ -3999,17 +4053,6 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "bbfa15b3dddfee50a0fff136974b3e1bde555604ba463834a7eb7deb6417705d"

-[[package]]
-name = "sha2"
-version = "0.10.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
-dependencies = [
- "cfg-if",
- "cpufeatures 0.2.17",
- "digest 0.10.7",
-]
-
 [[package]]
 name = "sha2"
 version = "0.11.0"
@@ -4130,8 +4173,7 @@ dependencies = [
 [[package]]
 name = "sqlx"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "378620ccc25c62c89d8be1c819e76a88d59bdcc3304733330788948e619bfd71"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "sqlx-core",
 "sqlx-macros",
@@ -4143,8 +4185,7 @@ dependencies = [
 [[package]]
 name = "sqlx-core"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "05b44e85bf579a8eeb4ceaa77a3a523baf2bf0e9bac7e40f405d537b5d2d5ccb"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "base64 0.22.1",
 "bytes",
@@ -4167,7 +4208,7 @@ dependencies = [
 "rustls",
 "serde",
 "serde_json",
- "sha2 0.10.9",
+ "sha2",
 "smallvec",
 "thiserror",
 "tokio",
@@ -4181,8 +4222,7 @@ dependencies = [
 [[package]]
 name = "sqlx-macros"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bd2b84f2bc39a5705ef27ec785a11c934a41bbd4a24941e257927cddc26b60bf"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -4194,8 +4234,7 @@ dependencies = [
 [[package]]
 name = "sqlx-macros-core"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fb8d96de5fdc85a5c4ec813432b523ec637e80ba98f046555f75f7908ddac7c3"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "cfg-if",
 "dotenvy",
@@ -4206,7 +4245,7 @@ dependencies = [
 "quote",
 "serde",
 "serde_json",
- "sha2 0.10.9",
+ "sha2",
 "sqlx-core",
 "sqlx-mysql",
 "sqlx-postgres",
@@ -4220,8 +4259,7 @@ dependencies = [
 [[package]]
 name = "sqlx-mysql"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "90b8020fe17c5f2c245bfa2505d7ef59c5604839527c740266ad2214acebea27"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "bitflags",
 "byteorder",
@@ -4238,7 +4276,7 @@ dependencies = [
 "percent-encoding",
 "serde",
 "sha1 0.11.0",
- "sha2 0.11.0",
+ "sha2",
 "sqlx-core",
 "thiserror",
 "tracing",
@@ -4248,8 +4286,7 @@ dependencies = [
 [[package]]
 name = "sqlx-postgres"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "87a2bdd6e83f6b3ea525ca9fee568030508b58355a43d0b2c1674d5f79dcd65e"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "atoi",
 "base64 0.22.1",
@@ -4272,7 +4309,7 @@ dependencies = [
 "rand 0.10.2",
 "serde",
 "serde_json",
- "sha2 0.11.0",
+ "sha2",
 "smallvec",
 "sqlx-core",
 "stringprep",
@@ -4285,8 +4322,7 @@ dependencies = [
 [[package]]
 name = "sqlx-sqlite"
 version = "0.9.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "488e99c397a62007e4229aec669a179816339afc6d2620ca6fa420dbee2e982c"
+source = "git+https://github.com/transact-rs/sqlx?rev=f1e94ec34dd5f11ad6488a3a8ac7988439a3f757#f1e94ec34dd5f11ad6488a3a8ac7988439a3f757"
 dependencies = [
 "atoi",
 "chrono",
@@ -4486,18 +4522,18 @@ dependencies = [

 [[package]]
 name = "thiserror"
-version = "2.0.20"
+version = "2.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
 dependencies = [
 "thiserror-impl",
 ]

 [[package]]
 name = "thiserror-impl"
-version = "2.0.20"
+version = "2.0.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
 dependencies = [
 "proc-macro2",
 "quote",
@@ -4692,8 +4728,8 @@ dependencies = [
 "bitflags",
 "bytes",
 "futures-util",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "pin-project-lite",
 "tower",
 "tower-layer",
@@ -4711,8 +4747,8 @@ dependencies = [
 "bytes",
 "futures-core",
 "futures-util",
- "http 1.5.0",
- "http-body 1.0.1",
+ "http",
+ "http-body",
 "http-body-util",
 "http-range-header",
 "httpdate",
@@ -4843,7 +4879,7 @@ dependencies = [
 "data-encoding",
 "flate2",
 "headers",
- "http 1.5.0",
+ "http",
 "httparse",
 "log",
 "rand 0.9.4",
@@ -4862,7 +4898,7 @@ checksum = "6c01152af293afb9c7c2a57e4b559c5620b421f6d133261c60dd2d0cdb38e6b8"
 dependencies = [
 "bytes",
 "data-encoding",
- "http 1.5.0",
+ "http",
 "httparse",
 "log",
 "rand 0.9.4",
@@ -4971,9 +5007,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"

 [[package]]
 name = "uuid"
-version = "1.26.1"
+version = "1.27.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2ef6dac1e96601b4fb3acccccff2139741fcb757cb9a36089bf5be91cfb285ce"
+checksum = "97277d36b9c3ace13e58fa6e753f8b0bbbf302a18dd193240d70f9e29681059a"
 dependencies = [
 "getrandom 0.4.3",
 "js-sys",
@@ -5158,6 +5194,12 @@ name = "whoami"
 version = "2.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "998767ef88740d1f5b0682a9c53c24431453923962269c2db68ee43788c5a40d"
+dependencies = [
+ "libc",
+ "libredox",
+ "objc2-system-configuration",
+ "web-sys",
+]

 [[package]]
 name = "winapi"
@@ -5361,7 +5403,7 @@ dependencies = [
 "base64 0.22.1",
 "deadpool",
 "futures",
- "http 1.5.0",
+ "http",
 "http-body-util",
 "hyper",
 "hyper-util",
@@ -5505,9 +5547,9 @@ dependencies = [

 [[package]]
 name = "zeroize"
-version = "1.9.0"
+version = "1.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
+checksum = "e13084392c5e4bc371903e2935a5eaeed24905a7511356b883835e18a78f6879"
 dependencies = [
 "zeroize_derive",
 ]
@@ -35,6 +35,20 @@ needless_collect = { level = "deny", priority = 7 }
 [profile.dev]
 debug = true

+# 测试保留真实密码参数和压缩数据量，优化热点依赖以减少 fixture 的计算开销。
+# test 继承 dev；workspace 代码仍保留默认调试与溢出检查。
+[profile.dev.package.argon2]
+opt-level = 2
+
+[profile.dev.package.blake2]
+opt-level = 2
+
+[profile.dev.package."sha2@0.11.0"]
+opt-level = 2
+
+[profile.dev.package."miniz_oxide@0.9.1"]
+opt-level = 2
+
 [profile.release]
 debug = false
 strip = "symbols"
@@ -45,3 +59,5 @@ panic = "abort"
 [patch.crates-io]
 # Upstream SOCKS IPv6 fix; remove once a release includes hyperium/hyper-util#302.
 hyper-util = { git = "https://github.com/hyperium/hyper-util", rev = "191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6" }
+# 固定上游 BEGIN 取消回滚修复，避免未结束事务复用；见 transact-rs/sqlx#4394
+sqlx = { git = "https://github.com/transact-rs/sqlx", rev = "f1e94ec34dd5f11ad6488a3a8ac7988439a3f757" }
@@ -1,397 +0,0 @@
-//! 网关唯一组合根：加载包级配置并连接各 Bundle。
-
-use gateway_core::engine::provider::{ProviderRegistry, RegistryError};
-use gateway_host::{ConfigError, HostConfig, LoadableConfig};
-use serde::Deserialize;
-
-const CONFIG_SCHEMA_VERSION: u32 = 1;
-
-/// 顶层配置只组合各包拥有的配置段，不解释任何业务字段。
-/// 各启动配置忽略未知字段，允许升级时保留旧配置；已知字段仍按类型和业务约束校验。
-#[derive(Debug, Deserialize)]
-pub struct GatewayConfig {
-    schema_version: u32,
-    host: HostConfig,
-    store: gateway_store::StoreConfig,
-    admin: gateway_admin::AdminConfig,
-    #[serde(default)]
-    client: gateway_admin::ClientConfig,
-    api: gateway_api::ApiConfig,
-    #[serde(default)]
-    openai: provider_openai::OpenAiConfig,
-}
-
-impl LoadableConfig for GatewayConfig {
-    const EXTERNAL_SECTIONS: &'static [&'static str] = &["services"];
-
-    fn resolve_and_validate(&mut self, source_dir: &std::path::Path) -> Result<(), ConfigError> {
-        if self.schema_version != CONFIG_SCHEMA_VERSION {
-            return Err(ConfigError::InvalidField("schema_version"));
-        }
-        self.api
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("api"))?;
-        self.host
-            .resolve_and_validate(source_dir, &self.api.asset_directory)?;
-        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
-        self.store
-            .resolve_and_validate(&runtime_data_dir)
-            .map_err(|_| ConfigError::InvalidField("store"))?;
-        self.admin
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("admin"))?;
-        self.client
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("client"))?;
-        self.openai
-            .resolve_and_validate(&runtime_data_dir)
-            .map_err(|_| ConfigError::InvalidField("openai"))?;
-        Ok(())
-    }
-}
-
-/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host。
-pub async fn run() -> Result<(), BootstrapError> {
-    launch(None).await.map(|_| ())
-}
-
-/// 这里只接收插件命名空间内的参数，不转交宿主配置或其他启动 secret。
-pub struct PluginCommand {
-    pub instance_id: Option<String>,
-    pub name: Option<String>,
-    pub arguments: Vec<String>,
-}
-
-impl PluginCommand {
-    fn is_help(&self) -> bool {
-        self.name.is_none()
-            || self
-                .arguments
-                .iter()
-                .any(|value| matches!(value.as_str(), "--help" | "-h"))
-    }
-}
-
-pub async fn plugin_command(
-    command: PluginCommand,
-) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
-    launch(Some(command)).await
-}
-
-async fn launch(
-    command: Option<PluginCommand>,
-) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
-    macro_rules! or_shutdown {
-        ($runtime:expr, $result:expr) => {
-            match $result {
-                Ok(value) => value,
-                Err(error) => {
-                    $runtime.shutdown().await;
-                    return Err(error.into());
-                }
-            }
-        };
-    }
-
-    let config = gateway_host::load_config::<GatewayConfig>()?;
-    let GatewayConfig {
-        schema_version: _,
-        host,
-        store,
-        admin,
-        client,
-        api,
-        openai,
-    } = config;
-
-    let plugin_cache = host.runtime_data_dir().join("plugins");
-    let host = if command.is_some() {
-        gateway_host::initialize_command_line(host).await?
-    } else {
-        gateway_host::initialize(host).await?
-    };
-    host.report_startup_ready("Host");
-    let help = command.as_ref().is_some_and(PluginCommand::is_help);
-    let mut store = if help {
-        gateway_store::initialize_read_only(store).await?
-    } else if command.is_some() {
-        gateway_store::initialize_command_line(store).await?
-    } else {
-        gateway_store::initialize(store).await?
-    };
-    host.report_startup_ready("Store");
-    let version = host
-        .system_operations()
-        .version()
-        .await
-        .map_err(|_| ConfigError::InvalidField("host.version"))?
-        .version;
-    let plugin_http = std::sync::Arc::new(gateway_host::outbound::HttpClient::new()?);
-    if let Some(command) = command.as_ref().filter(|_| help) {
-        let runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
-        let commands = or_shutdown!(runtime, runtime.prepare_command_line().await);
-        let stdout = commands.help(command.instance_id.as_deref(), command.name.as_deref());
-        commands.shutdown().await;
-        runtime.shutdown().await;
-        return Ok(gateway_plugin_runtime::PluginCommandOutput {
-            stdout: stdout?,
-            stderr: String::new(),
-            exit_code: 0,
-            saved_accounts: 0,
-        });
-    }
-    let provider_ports = store.provider_ports();
-    let mut openai = provider_openai::initialize(openai, provider_ports.clone()).await?;
-    host.report_startup_ready("OpenAI Provider");
-    let mut xai = provider_xai::initialize(provider_ports).await?;
-    host.report_startup_ready("xAI Provider");
-    let providers = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
-    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
-    let admin_providers = gateway_admin::ports::provider::ProviderAdminRegistry::new([
-        openai.admin_provider(),
-        xai.admin_provider(),
-    ])
-    .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?;
-    if let Some(command) = command {
-        let instance_id = or_shutdown!(
-            plugin_runtime,
-            command
-                .instance_id
-                .as_deref()
-                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件实例 ID 缺失"))
-        );
-        let name = or_shutdown!(
-            plugin_runtime,
-            command
-                .name
-                .as_deref()
-                .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件命令名缺失"))
-        );
-        let core = gateway_core::prepare_command_plane(
-            store.core_ports(),
-            providers.clone(),
-            Some(plugin_runtime.clone()),
-            Some(plugin_runtime.observer_registry()),
-            Some(plugin_runtime.policy_registry()),
-            Some(plugin_runtime.middleware_registry()),
-        );
-        let accounts = gateway_admin::initialize_plugin_accounts(
-            admin_providers.clone(),
-            store.admin_ports().accounts(),
-            core.snapshot_control(),
-        );
-        or_shutdown!(plugin_runtime, plugin_runtime.bind_account_ports(&accounts));
-        let keys = gateway_admin::initialize_plugin_client_keys(
-            admin_providers.clone(),
-            store.admin_ports().client_keys(),
-            core.snapshot_control(),
-        );
-        or_shutdown!(plugin_runtime, plugin_runtime.bind_client_key_ports(&keys));
-        let 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 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());
-    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),
-}
@@ -0,0 +1,134 @@
+//! 插件帮助只读启动；命令仅组装命令平面和必要写泵
+
+use super::{
+    BootstrapError, GatewayConfig,
+    plugins::{ManagementPorts, or_shutdown, prepare_plugins, service_middleware},
+    startup::{Environment, Mode, Providers},
+};
+
+/// 这里只接收插件命名空间内的参数，不转交宿主配置或其他启动 secret
+pub struct PluginCommand {
+    pub instance_id: Option<String>,
+    pub name: Option<String>,
+    pub arguments: Vec<String>,
+}
+
+impl PluginCommand {
+    fn is_help(&self) -> bool {
+        self.name.is_none()
+            || self
+                .arguments
+                .iter()
+                .any(|value| matches!(value.as_str(), "--help" | "-h"))
+    }
+}
+
+pub async fn plugin_command(
+    command: PluginCommand,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    if command.is_help() {
+        let environment = Environment::initialize(config.host, config.store, Mode::Help).await?;
+        help(command, environment).await
+    } else {
+        let environment = Environment::initialize(config.host, config.store, Mode::Command).await?;
+        let providers = Providers::initialize(config.openai, &environment).await?;
+        execute(command, environment, providers).await
+    }
+}
+
+async fn help(
+    command: PluginCommand,
+    environment: Environment,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let runtime = prepare_plugins(
+        &environment.store,
+        environment.plugin_cache,
+        &environment.version,
+        environment.plugin_http,
+    )?;
+    let commands = or_shutdown!(runtime, runtime.prepare_command_line().await);
+    let stdout = commands.help(command.instance_id.as_deref(), command.name.as_deref());
+    commands.shutdown().await;
+    runtime.shutdown().await;
+    Ok(gateway_plugin_runtime::PluginCommandOutput {
+        stdout: stdout?,
+        stderr: String::new(),
+        exit_code: 0,
+        saved_accounts: 0,
+    })
+}
+
+async fn execute(
+    command: PluginCommand,
+    environment: Environment,
+    providers: Providers,
+) -> Result<gateway_plugin_runtime::PluginCommandOutput, BootstrapError> {
+    let Environment {
+        host,
+        mut store,
+        plugin_cache,
+        version,
+        plugin_http,
+        ..
+    } = environment;
+    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http)?;
+    let instance_id = or_shutdown!(
+        plugin_runtime,
+        command
+            .instance_id
+            .as_deref()
+            .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件实例 ID 缺失"))
+    );
+    let name = or_shutdown!(
+        plugin_runtime,
+        command
+            .name
+            .as_deref()
+            .ok_or_else(|| gateway_admin::model::AdminError::invalid("插件命令名缺失"))
+    );
+    let core = gateway_core::prepare_command_plane(
+        store.core_ports(),
+        providers.core,
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.execution_registry()),
+    );
+    let management = ManagementPorts::new(&store, providers.admin.clone(), core.snapshot_control());
+    or_shutdown!(plugin_runtime, management.bind(&plugin_runtime));
+    let core = or_shutdown!(plugin_runtime, core.activate().await);
+    let nested_models = core.nested_model_execution_port();
+    let affinity_lookup = core.affinity_lookup_port();
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+    );
+    let settings = gateway_admin::initialize_settings(
+        store.admin_ports().settings(),
+        core.snapshot_control(),
+        providers.admin,
+        std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
+    );
+    let mut services = gateway_admin::public_service::Registry::new(service_middleware(
+        core.snapshots(),
+        &plugin_runtime,
+    ));
+    or_shutdown!(plugin_runtime, services.register_settings(&settings));
+    let services = std::sync::Arc::new(services);
+    or_shutdown!(plugin_runtime, plugin_runtime.bind_services(&services));
+    let commands = or_shutdown!(plugin_runtime, plugin_runtime.prepare_command_line().await);
+    let result = async {
+        store.start_command_line_writes()?;
+        Ok::<_, BootstrapError>(
+            commands
+                .execute_cancellable(instance_id, name, &command.arguments, &host.cancellation())
+                .await?,
+        )
+    }
+    .await;
+    commands.shutdown().await;
+    plugin_runtime.shutdown().await;
+    store.shutdown_command_line_writes().await?;
+    result
+}
@@ -0,0 +1,50 @@
+//! 网关顶层配置的加载、路径解析与跨模块参数校验
+
+use gateway_host::{ConfigError, HostConfig, LoadableConfig};
+use serde::Deserialize;
+
+const CONFIG_SCHEMA_VERSION: u32 = 1;
+
+/// 顶层配置只组合各包拥有的配置段，不解释任何业务字段
+/// 各启动配置忽略未知字段，允许升级时保留旧配置；已知字段仍按类型和业务约束校验
+#[derive(Debug, Deserialize)]
+pub struct GatewayConfig {
+    schema_version: u32,
+    pub(super) host: HostConfig,
+    pub(super) store: gateway_store::StoreConfig,
+    pub(super) admin: gateway_admin::AdminConfig,
+    #[serde(default)]
+    pub(super) client: gateway_admin::ClientConfig,
+    pub(super) api: gateway_api::ApiConfig,
+    #[serde(default)]
+    pub(super) openai: provider_openai::OpenAiConfig,
+}
+
+impl LoadableConfig for GatewayConfig {
+    const EXTERNAL_SECTIONS: &'static [&'static str] = &["services"];
+
+    fn resolve_and_validate(&mut self, source_dir: &std::path::Path) -> Result<(), ConfigError> {
+        if self.schema_version != CONFIG_SCHEMA_VERSION {
+            return Err(ConfigError::InvalidField("schema_version"));
+        }
+        self.api
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("api"))?;
+        self.host
+            .resolve_and_validate(source_dir, &self.api.asset_directory)?;
+        let runtime_data_dir = self.host.runtime_data_dir().to_path_buf();
+        self.store
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("store"))?;
+        self.admin
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("admin"))?;
+        self.client
+            .resolve_and_validate(source_dir)
+            .map_err(|_| ConfigError::InvalidField("client"))?;
+        self.openai
+            .resolve_and_validate(&runtime_data_dir)
+            .map_err(|_| ConfigError::InvalidField("openai"))?;
+        Ok(())
+    }
+}
@@ -0,0 +1,42 @@
+//! 网关唯一组合根：按启动模式连接各 Bundle
+
+mod command;
+mod config;
+mod plugins;
+mod server;
+mod startup;
+
+pub use command::{PluginCommand, plugin_command};
+pub use config::GatewayConfig;
+pub use server::run;
+
+/// 组合根只保留包级错误分类，不展开内部实现或敏感配置
+#[derive(Debug, thiserror::Error)]
+pub enum BootstrapError {
+    #[error(transparent)]
+    Worker(#[from] gateway_core::task::WorkerDefinitionError),
+    #[error(transparent)]
+    PluginCommand(#[from] gateway_plugin_runtime::PluginCommandError),
+    #[error(transparent)]
+    Config(#[from] gateway_host::ConfigError),
+    #[error(transparent)]
+    Host(#[from] gateway_host::HostError),
+    #[error(transparent)]
+    Outbound(#[from] gateway_host::outbound::HttpError),
+    #[error(transparent)]
+    Store(#[from] gateway_store::StoreError),
+    #[error(transparent)]
+    CommandStoreDrain(#[from] gateway_store::CommandStoreDrainError),
+    #[error(transparent)]
+    OpenAi(#[from] provider_openai::OpenAiInitializeError),
+    #[error(transparent)]
+    Xai(#[from] provider_xai::XaiInitializeError),
+    #[error(transparent)]
+    Registry(#[from] gateway_core::engine::provider::RegistryError),
+    #[error(transparent)]
+    Core(#[from] gateway_core::CoreError),
+    #[error(transparent)]
+    Admin(#[from] gateway_admin::model::AdminError),
+    #[error(transparent)]
+    Api(#[from] gateway_api::ApiError),
+}
@@ -0,0 +1,108 @@
+//! 插件 Runtime 的组装与回调资源持有；服务和命令模式复用同一组管理端口
+
+use std::sync::Arc;
+
+use gateway_admin::{
+    model::AdminError,
+    ports::{
+        plugin_accounts::PluginAccountAccess, plugin_client_keys::PluginClientKeyAccess,
+        plugin_resources::PluginResourceAccess, provider::ProviderAdminRegistry,
+    },
+};
+use gateway_core::runtime::{RuntimeSnapshotHandle, SnapshotControl};
+use gateway_host::ConfigError;
+use gateway_plugin_runtime::PluginRuntime;
+
+use super::BootstrapError;
+
+// 必须在调用方仍持有 Core 和回调资源时异步关闭，不能先退出该作用域再清理
+macro_rules! or_shutdown {
+    ($runtime:expr, $result:expr) => {
+        match $result {
+            Ok(value) => value,
+            Err(error) => {
+                $runtime.shutdown().await;
+                return Err(error.into());
+            }
+        }
+    };
+}
+
+pub(super) use or_shutdown;
+
+pub(super) struct ManagementPorts {
+    // Runtime 保存 Weak；组合根持有这些 Arc，直到插件全部关闭
+    pub(super) accounts: Arc<dyn PluginAccountAccess>,
+    keys: Arc<dyn PluginClientKeyAccess>,
+    resources: Arc<dyn PluginResourceAccess>,
+}
+
+impl ManagementPorts {
+    pub(super) fn new(
+        store: &gateway_store::StoreBundle,
+        providers: ProviderAdminRegistry,
+        snapshot: Arc<dyn SnapshotControl>,
+    ) -> Self {
+        let ports = store.admin_ports();
+        Self {
+            accounts: gateway_admin::initialize_plugin_accounts(
+                providers.clone(),
+                ports.accounts(),
+                snapshot.clone(),
+            ),
+            keys: gateway_admin::initialize_plugin_client_keys(
+                providers,
+                ports.client_keys(),
+                snapshot.clone(),
+            ),
+            resources: gateway_admin::initialize_plugin_resources(
+                ports.plugin_resources(),
+                snapshot,
+            ),
+        }
+    }
+
+    pub(super) fn bind(&self, runtime: &PluginRuntime) -> Result<(), AdminError> {
+        runtime.bind_account_ports(&self.accounts)?;
+        runtime.bind_client_key_ports(&self.keys)?;
+        runtime.bind_resource_ports(&self.resources)
+    }
+}
+
+pub(super) fn service_middleware(
+    snapshots: RuntimeSnapshotHandle,
+    runtime: &PluginRuntime,
+) -> gateway_admin::public_service::PlanSource {
+    let middleware = runtime.execution_registry();
+    Arc::new(move || {
+        let snapshot = snapshots.snapshot_for_diagnostics()?;
+        middleware.middleware(snapshot.extensions()?)
+    })
+}
+
+pub(super) fn prepare_plugins(
+    store: &gateway_store::StoreBundle,
+    plugin_cache: std::path::PathBuf,
+    version: &str,
+    http: Arc<gateway_host::outbound::HttpClient>,
+) -> Result<Arc<gateway_plugin_runtime::PluginRuntime>, BootstrapError> {
+    Ok(Arc::new(
+        gateway_plugin_runtime::PluginRuntime::new(
+            store.admin_ports().plugins(),
+            store.admin_ports().plugin_state(),
+            gateway_plugin_runtime::PluginRuntimeConfig {
+                cache_directory: plugin_cache,
+                host_version: version
+                    .trim_start_matches('v')
+                    .parse()
+                    .map_err(|_| ConfigError::InvalidField("host.version"))?,
+                package_limits: gateway_plugin_runtime::PackageLimits::default(),
+                rpc_limits: gateway_plugin_runtime::RpcLimits::default(),
+                restart_circuit: Default::default(),
+            },
+            http,
+            Arc::new(gateway_host::process::ProcessSupervisor::default()),
+        )
+        .with_oauth_pending(store.provider_ports().oauth_pending()),
+    ))
+}
@@ -0,0 +1,172 @@
+//! 服务模式完成全部组装后交给 Host 监听，并在停止监听与 Worker 收尾后关闭插件
+
+use gateway_host::ConfigError;
+
+use super::{
+    BootstrapError, GatewayConfig,
+    plugins::{ManagementPorts, or_shutdown, prepare_plugins, service_middleware},
+    startup::{Environment, Mode, Providers},
+};
+
+/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host
+pub async fn run() -> Result<(), BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    let environment = Environment::initialize(config.host, config.store, Mode::Server).await?;
+    let mut providers = Providers::initialize(config.openai, &environment).await?;
+    let Environment {
+        host,
+        mut store,
+        timezone,
+        plugin_cache,
+        version,
+        plugin_http,
+    } = environment;
+    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
+    let core = gateway_core::prepare(
+        store.core_ports(),
+        providers.core,
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.execution_registry()),
+        Some(plugin_runtime.frontend_authentication_registry()),
+    );
+    let management = ManagementPorts::new(&store, providers.admin.clone(), core.snapshot_control());
+    or_shutdown!(plugin_runtime, management.bind(&plugin_runtime));
+    let mut core = or_shutdown!(plugin_runtime, core.activate().await);
+    let nested_models = core.nested_model_execution_port();
+    let affinity_lookup = core.affinity_lookup_port();
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_model_ports(&nested_models, &affinity_lookup)
+    );
+    host.report_startup_ready("Core");
+    let host_version = or_shutdown!(
+        plugin_runtime,
+        version
+            .trim_start_matches('v')
+            .parse()
+            .map_err(|_| ConfigError::InvalidField("host.version"))
+    );
+    let plugin_inspector = std::sync::Arc::new(gateway_plugin_runtime::PackageInspector::new(
+        gateway_plugin_runtime::PackageLimits::default(),
+        host_version,
+    ));
+    let plugin_distribution = std::sync::Arc::new(or_shutdown!(
+        plugin_runtime,
+        gateway_host::plugin_distribution::HttpPluginDistribution::new(plugin_http)
+    ));
+    let analytics_worker = or_shutdown!(
+        plugin_runtime,
+        store.request_analytics_worker(std::sync::Arc::new(
+            gateway_admin::ProviderUsageBillingProjector::new(providers.admin.clone()),
+        ))
+    );
+    let mut admin = or_shutdown!(
+        plugin_runtime,
+        gateway_admin::initialize_with_plugin_accounts(
+            config.admin,
+            config.client,
+            store.admin_ports(),
+            gateway_admin::AdminRuntimePorts {
+                timezone,
+                service_middleware: service_middleware(core.snapshots(), &plugin_runtime),
+                providers: providers.admin,
+                plugin_preparation: plugin_runtime.clone(),
+                plugin_management: plugin_runtime.clone(),
+                published_snapshot: core.snapshots(),
+                plugin_inspector,
+                plugin_distribution,
+                pricing_source: std::sync::Arc::new(gateway_host::pricing::ModelsDevPricing),
+                snapshot: core.snapshot_control(),
+                account_probe: core.account_probe(),
+                proxy_probe: host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
+                client_distribution: host.client_distribution_resolver(),
+                system: host.system_operations(),
+                client_key_verifier: core.client_key_verifier(),
+            },
+            management.accounts.clone(),
+        )
+        .await
+    );
+    let official_files = host.official_plugin_release_files();
+    let official_identity = host.official_plugin_release_identity();
+    let official_import = or_shutdown!(
+        plugin_runtime,
+        admin
+            .services()
+            .plugins()
+            .import_official_release(
+                official_files.as_ref(),
+                &official_identity,
+                &gateway_admin::model::MutationContext {
+                    actor: gateway_admin::model::MutationActor::System,
+                    request_id: "startup-official-plugin-import".to_owned(),
+                },
+            )
+            .await
+    );
+    if official_import.artifacts > 0 {
+        host.report_startup_ready("Official plugins");
+    }
+    host.report_startup_ready("Admin");
+
+    let mut probes = store.health_probes();
+    probes.extend(core.health_probes());
+    probes.push(host.logging_health_probe());
+    let api = or_shutdown!(
+        plugin_runtime,
+        gateway_api::initialize(
+            config.api,
+            core.execution_service(),
+            admin.services(),
+            probes,
+            host.worker_health(),
+            host.connection_lifecycle(),
+            store.diagnostics(),
+        )
+    )
+    .with_middleware({
+        let snapshots = core.snapshots();
+        let middleware = plugin_runtime.execution_registry();
+        move |snapshot| {
+            if let Some(snapshot) = snapshot {
+                return middleware.middleware(snapshot.extensions()?);
+            }
+            // 数据面未就绪时，管理与诊断路由仍可使用发布候选中的插件
+            let diagnostic = snapshots.snapshot_for_diagnostics()?;
+            middleware.middleware(diagnostic.extensions()?)
+        }
+    });
+    let http_dispatcher = api.dispatcher();
+    or_shutdown!(plugin_runtime, plugin_runtime.bind_http(&http_dispatcher));
+    host.report_startup_ready("API");
+
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_services(&admin.services().public_services())
+    );
+
+    let mut plan = store.take_worker_contributions();
+    plan.push(analytics_worker);
+    plan.push(or_shutdown!(
+        plugin_runtime,
+        gateway_host::retention::worker(store.retention())
+    ));
+    plan.extend(core.take_worker_contributions());
+    plan.extend(providers.openai.take_worker_contributions());
+    plan.extend(providers.xai.take_worker_contributions());
+    plan.extend(admin.take_worker_contributions());
+    plan.push(or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.maintenance_worker(core.snapshots())
+    ));
+    or_shutdown!(
+        plugin_runtime,
+        host.start_workers(plan, store.worker_leader_lease(), store.diagnostics())
+    );
+    host.report_startup_ready("Workers");
+    let served = host.serve(api.router()).await;
+    plugin_runtime.shutdown().await;
+    Ok(served?)
+}
@@ -0,0 +1,94 @@
+//! 启动模式共享的基础设施与 Provider 组装，不启动 HTTP 或 Worker
+
+use std::{path::PathBuf, sync::Arc};
+
+use gateway_admin::ports::provider::ProviderAdminRegistry;
+use gateway_core::{engine::provider::ProviderRegistry, time::DeploymentTimeZone};
+use gateway_host::{ConfigError, HostBundle, HostConfig, outbound::HttpClient};
+use gateway_store::{StoreBundle, StoreConfig};
+
+use super::BootstrapError;
+
+pub(super) enum Mode {
+    Server,
+    Command,
+    Help,
+}
+
+pub(super) struct Environment {
+    pub(super) host: HostBundle,
+    pub(super) store: StoreBundle,
+    pub(super) timezone: DeploymentTimeZone,
+    pub(super) plugin_cache: PathBuf,
+    pub(super) version: String,
+    pub(super) plugin_http: Arc<HttpClient>,
+}
+
+impl Environment {
+    pub(super) async fn initialize(
+        host: HostConfig,
+        store: StoreConfig,
+        mode: Mode,
+    ) -> Result<Self, BootstrapError> {
+        let timezone = host.timezone;
+        let store = store.with_timezone(timezone);
+        let plugin_cache = host.runtime_data_dir().join("plugins");
+        let host = match mode {
+            Mode::Server => gateway_host::initialize(host).await?,
+            Mode::Command | Mode::Help => gateway_host::initialize_command_line(host).await?,
+        };
+        host.report_startup_ready("Host");
+        let store = match mode {
+            Mode::Server => gateway_store::initialize(store).await?,
+            Mode::Command => gateway_store::initialize_command_line(store).await?,
+            Mode::Help => gateway_store::initialize_read_only(store).await?,
+        };
+        host.report_startup_ready("Store");
+        let version = host
+            .system_operations()
+            .version()
+            .await
+            .map_err(|_| ConfigError::InvalidField("host.version"))?
+            .version;
+        let plugin_http = Arc::new(HttpClient::new()?);
+        Ok(Self {
+            host,
+            store,
+            timezone,
+            plugin_cache,
+            version,
+            plugin_http,
+        })
+    }
+}
+
+pub(super) struct Providers {
+    pub(super) openai: provider_openai::ProviderBundle,
+    pub(super) xai: provider_xai::ProviderBundle,
+    pub(super) core: ProviderRegistry,
+    pub(super) admin: ProviderAdminRegistry,
+}
+
+impl Providers {
+    pub(super) async fn initialize(
+        config: provider_openai::OpenAiConfig,
+        environment: &Environment,
+    ) -> Result<Self, BootstrapError> {
+        let ports = environment.store.provider_ports();
+        let openai =
+            provider_openai::initialize(config.with_timezone(environment.timezone), ports.clone())
+                .await?;
+        environment.host.report_startup_ready("OpenAI Provider");
+        let xai = provider_xai::initialize(ports).await?;
+        environment.host.report_startup_ready("xAI Provider");
+        let core = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
+        let admin = ProviderAdminRegistry::new([openai.admin_provider(), xai.admin_provider()])
+            .map_err(|_| gateway_admin::model::AdminError::invalid("Provider 管理身份冲突"))?;
+        Ok(Self {
+            openai,
+            xai,
+            core,
+            admin,
+        })
+    }
+}
@@ -1,3 +1,3 @@
-//! 网关进程组装根。
+//! 网关进程组装根

 pub mod bootstrap;
@@ -1,3 +1,5 @@
+//! 网关命令行入口，选择启动模式并创建异步运行时
+
 use std::{
    env,
    error::Error,
@@ -1,4 +1,4 @@
-//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
+//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验

 use std::{
    collections::{BTreeMap, BTreeSet},
@@ -8,7 +8,7 @@ use std::{

 use syn::{Item, visit::Visit};

-/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
+/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则
 pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
    "apps/gateway",
    "apps/plugin-cli",
@@ -76,16 +76,28 @@ fn core_value_owners_do_not_depend_on_execution_or_routing() {
            "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("policy/") => {
+                Some(&["account", "identity", "policy", "validation"])
+            }
+            path if path.starts_with("settings/") => Some(&[
+                "account",
+                "concurrency",
+                "identity",
+                "metering",
+                "policy",
+                "settings",
+            ]),
            path if path.starts_with("account/") => Some(&["account", "identity", "validation"]),
            _ => None,
        };
        let Some(allowed) = allowed else { continue };
        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
        let syntax = syn::parse_file(&source).expect("parse core source");
-        let mut references = CrateReferences::default();
+        let mut references = CrateReferences::in_module(&relative);
        references.visit_file(&syntax);
-        for dependency in references.0 {
+        // 相对路径中的 self 指向当前 owner，不是跨 owner 依赖
+        references.owners.remove(&references.module_path[0]);
+        for dependency in references.owners {
            assert!(
                allowed.contains(&dependency.as_str()),
                "{} must not depend on crate::{dependency}",
@@ -95,49 +107,155 @@ fn core_value_owners_do_not_depend_on_execution_or_routing() {
    }
 }

+#[test]
+fn core_owner_paths_form_a_dag() {
+    let root = backend_root().join("crates/gateway-core/src");
+    let mut graph = BTreeMap::<String, BTreeSet<String>>::new();
+    for relative in super::rust_files(&root) {
+        if relative == Path::new("lib.rs") {
+            continue;
+        }
+        let mut references = CrateReferences::in_module(&relative);
+        let owner = references.module_path[0].clone();
+        let source = fs::read_to_string(root.join(&relative)).expect("read core source");
+        references.visit_file(&syn::parse_file(&source).expect("parse core source"));
+        references.owners.remove(&owner);
+        graph.entry(owner).or_default().extend(references.owners);
+    }
+    for owner in graph.keys() {
+        let mut pending = graph[owner].iter().cloned().collect::<Vec<_>>();
+        let mut visited = BTreeSet::new();
+        while let Some(dependency) = pending.pop() {
+            assert_ne!(
+                &dependency, owner,
+                "Core owner dependency cycle reaches {owner}"
+            );
+            if visited.insert(dependency.clone())
+                && let Some(next) = graph.get(&dependency)
+            {
+                pending.extend(next.iter().cloned());
+            }
+        }
+    }
+}
+
+#[test]
+fn core_reference_scan_resolves_groups_reexports_and_relative_paths() {
+    let syntax = syn::parse_file(
+        r#"
+        pub use crate::{engine::AttemptContext, settings::SettingsValues as Values};
+        use super::super::runtime as publication;
+        use self::compiled::Value;
+        // crate::ignored::Comment
+        const EXAMPLE: &str = "crate::ignored::Literal";
+        "#,
+    )
+    .expect("parse reference fixture");
+    let mut references = CrateReferences::in_module(Path::new("routing/snapshot.rs"));
+    references.visit_file(&syntax);
+    assert_eq!(
+        references.owners,
+        BTreeSet::from([
+            "engine".to_owned(),
+            "settings".to_owned(),
+            "runtime".to_owned(),
+            "routing".to_owned(),
+        ])
+    );
+}
+
 #[derive(Default)]
-struct CrateReferences(BTreeSet<String>);
+struct CrateReferences {
+    owners: BTreeSet<String>,
+    module_path: Vec<String>,
+}

 impl<'ast> Visit<'ast> for CrateReferences {
    fn visit_path(&mut self, path: &'ast syn::Path) {
-        let mut segments = path.segments.iter();
-        if segments
-            .next()
-            .is_some_and(|segment| segment.ident == "crate")
-            && let Some(owner) = segments.next()
-        {
-            self.0.insert(owner.ident.to_string());
-        }
+        self.record(
+            &path
+                .segments
+                .iter()
+                .map(|part| part.ident.to_string())
+                .collect::<Vec<_>>(),
+        );
        syn::visit::visit_path(self, path);
    }

    fn visit_item_use(&mut self, item: &'ast syn::ItemUse) {
-        self.use_tree(&item.tree, false);
+        self.use_tree(&item.tree, &mut Vec::new());
    }
 }

 impl CrateReferences {
-    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
+    fn in_module(relative: &Path) -> Self {
+        let mut module = relative
+            .with_extension("")
+            .components()
+            .map(|part| {
+                part.as_os_str()
+                    .to_str()
+                    .expect("UTF-8 module path")
+                    .to_owned()
+            })
+            .collect::<Vec<_>>();
+        if module.last().is_some_and(|part| part == "mod") {
+            module.pop();
+        }
+        Self {
+            owners: BTreeSet::new(),
+            module_path: module,
+        }
+    }
+
+    fn record(&mut self, path: &[String]) {
+        let Some(first) = path.first() else { return };
+        let owner = if first == "crate" {
+            path.get(1).cloned()
+        } else if first == "self" || first == "super" {
+            let mut module = self.module_path.clone();
+            let mut rest = path;
+            while rest
+                .first()
+                .is_some_and(|part| part == "super" || part == "self")
+            {
+                if rest[0] == "super" {
+                    module.pop();
+                }
+                rest = &rest[1..];
+            }
+            module.first().or_else(|| rest.first()).cloned()
+        } else {
+            None
+        };
+        if let Some(owner) = owner {
+            self.owners.insert(owner);
+        }
+    }
+
+    fn use_tree(&mut self, tree: &syn::UseTree, prefix: &mut Vec<String>) {
        match tree {
-            syn::UseTree::Path(path) if crate_root => {
-                self.0.insert(path.ident.to_string());
+            syn::UseTree::Path(path) => {
+                prefix.push(path.ident.to_string());
+                self.use_tree(&path.tree, prefix);
+                prefix.pop();
            }
-            syn::UseTree::Name(name) if crate_root => {
-                self.0.insert(name.ident.to_string());
+            syn::UseTree::Name(name) => {
+                prefix.push(name.ident.to_string());
+                self.record(prefix);
+                prefix.pop();
            }
-            syn::UseTree::Rename(rename) if crate_root => {
-                self.0.insert(rename.ident.to_string());
+            syn::UseTree::Rename(rename) => {
+                prefix.push(rename.ident.to_string());
+                self.record(prefix);
+                prefix.pop();
            }
-            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
            syn::UseTree::Group(group) => {
                for item in &group.items {
-                    self.use_tree(item, crate_root);
+                    self.use_tree(item, prefix);
                }
            }
-            syn::UseTree::Glob(_) if crate_root => {
-                self.0.insert("*".to_owned());
-            }
-            _ => {}
+            syn::UseTree::Glob(_) => self.record(prefix),
        }
    }
 }
@@ -173,7 +291,7 @@ fn gateway_admin_stays_free_of_infrastructure_dependencies() {
    );
 }

-/// workspace 包名到冻结成员路径的映射。
+/// workspace 包名到冻结成员路径的映射
 const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
    ("codex-proxy-rs", "apps/gateway"),
    ("codex-proxy-plugin-cli", "apps/plugin-cli"),
@@ -189,7 +307,7 @@ const PACKAGE_TO_MEMBER: &[(&str, &str)] = &[
    ("provider-xai", "crates/providers/xai"),
 ];

-/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计
 const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
    ("crates/gateway-plugin/sdk", &["call", "client"]),
    ("crates/gateway-plugin/runtime", &[]),
@@ -205,6 +323,7 @@ const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
            "plugin_distribution",
            "process",
            "proxy_probe",
+            "retention",
            "serve",
            "system_update",
            "workers",
@@ -215,16 +334,16 @@ const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
        "crates/providers/openai",
        &["config", "credential", "transport"],
    ),
-    ("crates/providers/xai", &["credential", "transport"]),
+    ("crates/providers/xai", &["transport"]),
 ];

-/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景。
+/// 不对应单一生产模块、而是校验 crate/workspace 整体契约的根级测试场景
 const ROOT_TEST_SCENARIOS: &[(&str, &[&str])] = &[
    ("apps/gateway", &["architecture"]),
    ("crates/gateway-api", &["architecture"]),
 ];

-/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表。
+/// 冻结的 workspace 内部运行时依赖边；新增/删除任何边都必须同步本表
 const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
    ("codex-proxy-plugin-cli", "gateway-plugin-sdk"),
    ("codex-proxy-rs", "gateway-admin"),
@@ -378,7 +497,9 @@ 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 src = member_root.join("src");
+        assert_module_tree(&src, &["lib.rs", "main.rs"]);
+        assert_directory_modules_have_children(&src, &["lib.rs", "main.rs"]);

        let tests = member_root.join("tests");
        if tests.is_dir() {
@@ -391,6 +512,29 @@ fn workspace_modules_follow_conventional_file_layout() {
    }
 }

+fn assert_directory_modules_have_children(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))
+            || relative.file_name().and_then(|value| value.to_str()) != Some("mod.rs")
+        {
+            continue;
+        }
+
+        let directory = relative.parent().expect("mod.rs parent");
+        assert!(
+            files
+                .iter()
+                .any(|candidate| candidate != relative && candidate.starts_with(directory)),
+            "{} is a leaf module and must use {}",
+            root.join(relative).display(),
+            root.join(directory).with_extension("rs").display(),
+        );
+    }
+}
+
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 enum ModuleLayout {
    File,
@@ -444,7 +588,7 @@ fn integration_tests_mirror_production_module_tree() {
    }
 }

-/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明。
+/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明
 fn test_source_roots() -> BTreeMap<PathBuf, Vec<String>> {
    let metadata = cargo_metadata_json();
    let mut roots = BTreeMap::<PathBuf, Vec<String>>::new();
@@ -498,6 +642,8 @@ fn root_test_scenario_allowed(member: &str, module: &Path) -> bool {

 fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
    let files = super::rust_files(root);
+    // 同一父模块的所有子文件复用一次语法解析，计数仍保留重复声明检查
+    let mut declarations = BTreeMap::<PathBuf, BTreeMap<String, usize>>::new();
    for relative in &files {
        if crate_roots
            .iter()
@@ -560,7 +706,14 @@ fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
        };
        let declaration_count = declaration_parents
            .iter()
-            .map(|path| external_module_declaration_count(path, module_name))
+            .map(|path| {
+                declarations
+                    .entry(path.clone())
+                    .or_insert_with(|| external_module_declarations(path))
+                    .get(module_name)
+                    .copied()
+                    .unwrap_or_default()
+            })
            .sum::<usize>();
        assert_eq!(
            declaration_count,
@@ -571,23 +724,21 @@ fn assert_module_tree(root: &Path, crate_roots: &[&str]) {
    }
 }

-fn external_module_declaration_count(path: &Path, module_name: &str) -> usize {
+fn external_module_declarations(path: &Path) -> BTreeMap<String, usize> {
    if !path.is_file() {
-        return 0;
+        return BTreeMap::new();
    }
    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()
+    let mut declarations = BTreeMap::new();
+    for item in syntax.items {
+        if let Item::Mod(module) = item
+            && module.content.is_none()
+        {
+            *declarations.entry(module.ident.to_string()).or_default() += 1;
+        }
+    }
+    declarations
 }

 pub(super) fn backend_root() -> PathBuf {
@@ -611,7 +762,7 @@ fn cargo_metadata_json() -> serde_json::Value {
    serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
 }

-/// 提取成员 `[dependencies]` 段内声明的依赖名;段落以下一个 `[` 表头结束。
+/// 提取成员 `[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");
@@ -0,0 +1,51 @@
+//! 验证网关基础命令无需加载配置，并拒绝非法或多余参数
+
+use std::{fs, process::Command};
+
+#[test]
+fn basic_cli_options_do_not_load_configuration_and_reject_unexpected_arguments() {
+    let directory = tempfile::tempdir().unwrap();
+    fs::create_dir(directory.path().join("deploy")).unwrap();
+    fs::write(directory.path().join("deploy/config.yaml"), "invalid: [").unwrap();
+    for flag in ["--help", "-h", "help", "--version", "-V"] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .arg(flag)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(output.status.success(), "{flag}");
+        assert!(!output.stdout.is_empty());
+        assert!(output.stderr.is_empty());
+    }
+    for args in [
+        vec!["unknown"],
+        vec!["--help", "extra"],
+        vec!["serve", "extra"],
+    ] {
+        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+            .args(args)
+            .current_dir(directory.path())
+            .env_clear()
+            .output()
+            .unwrap();
+        assert!(!output.status.success());
+        assert!(output.stdout.is_empty());
+        assert!(!String::from_utf8_lossy(&output.stderr).contains("configuration"));
+    }
+}
+
+#[cfg(unix)]
+#[test]
+fn non_utf8_command_is_not_interpreted_as_serve() {
+    use std::os::unix::ffi::OsStringExt as _;
+
+    let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
+        .arg(std::ffi::OsString::from_vec(vec![0xff]))
+        .env_clear()
+        .output()
+        .unwrap();
+    assert!(!output.status.success());
+    assert!(output.stdout.is_empty());
+    assert!(String::from_utf8_lossy(&output.stderr).contains("command must be UTF-8"));
+}
@@ -1,207 +1,16 @@
+//! 验证顶层配置加载、路径解析、显式覆盖与敏感字段脱敏
+
 use std::{fs, process::Command};

 use codex_proxy_rs::bootstrap::GatewayConfig;
 use gateway_host::LoadableConfig;

-const CONFIG_EXAMPLE: &str = include_str!("../../../../deploy/config.example.yaml");
+const CONFIG_EXAMPLE: &str = include_str!("../../../../../deploy/config.example.yaml");
 const POSTGRES_PASSWORD: &str = "111111111111111111111111111111111111111111111111";
 const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
 const ADMIN_PASSWORD: &str = "test-admin-password";
 const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";

-#[test]
-fn basic_cli_options_do_not_load_configuration_and_reject_unexpected_arguments() {
-    let directory = tempfile::tempdir().unwrap();
-    fs::create_dir(directory.path().join("deploy")).unwrap();
-    fs::write(directory.path().join("deploy/config.yaml"), "invalid: [").unwrap();
-    for flag in ["--help", "-h", "help", "--version", "-V"] {
-        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-            .arg(flag)
-            .current_dir(directory.path())
-            .env_clear()
-            .output()
-            .unwrap();
-        assert!(output.status.success(), "{flag}");
-        assert!(!output.stdout.is_empty());
-        assert!(output.stderr.is_empty());
-    }
-    for args in [
-        vec!["unknown"],
-        vec!["--help", "extra"],
-        vec!["serve", "extra"],
-    ] {
-        let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-            .args(args)
-            .current_dir(directory.path())
-            .env_clear()
-            .output()
-            .unwrap();
-        assert!(!output.status.success());
-        assert!(output.stdout.is_empty());
-        assert!(!String::from_utf8_lossy(&output.stderr).contains("configuration"));
-    }
-}
-
-#[cfg(unix)]
-#[test]
-fn non_utf8_command_is_not_interpreted_as_serve() {
-    use std::os::unix::ffi::OsStringExt as _;
-
-    let output = Command::new(env!("CARGO_BIN_EXE_codex-proxy-rs"))
-        .arg(std::ffi::OsString::from_vec(vec![0xff]))
-        .env_clear()
-        .output()
-        .unwrap();
-    assert!(!output.status.success());
-    assert!(output.stdout.is_empty());
-    assert!(String::from_utf8_lossy(&output.stderr).contains("command must be UTF-8"));
-}
-
-#[tokio::test]
-async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
-    use gateway_admin::ports::proxy::ProxyProbe;
-    use gateway_core::account::OutboundProxy;
-    use gateway_host::proxy_probe::HttpProxyProbe;
-    use std::{sync::Arc, time::Duration};
-    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
-    use tokio_rustls::{
-        TlsAcceptor,
-        rustls::{
-            ServerConfig,
-            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
-        },
-    };
-
-    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
-    let Ok(directory) = std::env::var(CHILD_ENV) else {
-        let directory = tempfile::tempdir().unwrap();
-        generate_proxy_test_certificates(directory.path());
-        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置。
-        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
-            let mut child = Command::new(std::env::current_exe().unwrap());
-            child
-                .args([
-                    "--exact",
-                    "bootstrap::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
-                    "--nocapture",
-                ])
-                .env(CHILD_ENV, directory.path())
-                .env_remove("CODEX_CA_CERTIFICATE")
-                .env_remove("SSL_CERT_FILE")
-                .env(ca_env, directory.path().join("ca.pem"));
-            if ca_env == "CODEX_CA_CERTIFICATE" {
-                child.env(
-                    "SSL_CERT_FILE",
-                    directory.path().join("missing-fallback.pem"),
-                );
-            }
-            let output = child.output().unwrap();
-            assert!(
-                output.status.success(),
-                "{ca_env}: {}\n{}",
-                String::from_utf8_lossy(&output.stdout),
-                String::from_utf8_lossy(&output.stderr)
-            );
-        }
-        return;
-    };
-    provider_openai::ensure_rustls_provider();
-    let directory = std::path::Path::new(&directory);
-    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
-    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
-    let acceptor = TlsAcceptor::from(Arc::new(
-        ServerConfig::builder()
-            .with_no_client_auth()
-            .with_single_cert(vec![certificate], key)
-            .unwrap(),
-    ));
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
-    let proxy =
-        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
-    let server = tokio::spawn(async move {
-        let (socket, _) = listener.accept().await.unwrap();
-        let mut stream = acceptor.accept(socket).await.unwrap();
-        let mut request = Vec::new();
-        while !request.ends_with(b"\r\n\r\n") {
-            assert!(request.len() < 8192);
-            request.push(stream.read_u8().await.unwrap());
-        }
-        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
-        let body = "{\"ip\":\"203.0.113.8\"}";
-        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
-        stream.shutdown().await.unwrap();
-    });
-    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
-        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
-    let result = probe.test(&proxy, false).await;
-    assert!(result.success, "{}", result.message);
-    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
-    tokio::time::timeout(Duration::from_secs(5), server)
-        .await
-        .unwrap()
-        .unwrap();
-}
-
-fn generate_proxy_test_certificates(directory: &std::path::Path) {
-    let openssl = |args: &[&str]| {
-        let output = Command::new("openssl")
-            .args(args)
-            .current_dir(directory)
-            .output()
-            .unwrap();
-        assert!(
-            output.status.success(),
-            "{}",
-            String::from_utf8_lossy(&output.stderr)
-        );
-    };
-    openssl(&[
-        "req",
-        "-x509",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "ca.key",
-        "-out",
-        "ca.pem",
-        "-days",
-        "1",
-        "-subj",
-        "/CN=Proxy Test CA",
-    ]);
-    openssl(&[
-        "req",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "server.key",
-        "-out",
-        "server.csr",
-        "-subj",
-        "/CN=localhost",
-    ]);
-    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
-    openssl(&[
-        "x509",
-        "-req",
-        "-in",
-        "server.csr",
-        "-CA",
-        "ca.pem",
-        "-CAkey",
-        "ca.key",
-        "-CAcreateserial",
-        "-out",
-        "server.pem",
-        "-days",
-        "1",
-        "-extfile",
-        "extensions",
-    ]);
-}
-
 #[test]
 fn config_loader_should_load_complete_terminal_example() {
    parse_config(&valid_config()).expect("terminal config example");
@@ -220,7 +29,7 @@ fn config_loader_should_resolve_paths_relative_to_config_file() {
 fn config_loader_should_share_resolved_assets_with_system_update() {
    const CHILD_ENV: &str = "CPR_TEST_UPDATE_ASSETS_CHILD";
    let Ok(case) = std::env::var(CHILD_ENV) else {
-        // 使用子进程覆盖无环境变量、Docker 路径和相对路径，避免污染并行测试。
+        // 使用子进程覆盖无环境变量、Docker 路径和相对路径，避免污染并行测试
        for (case, web_dist) in [
            ("binary", None),
            ("docker", Some("/app/web/dist")),
@@ -230,7 +39,7 @@ fn config_loader_should_share_resolved_assets_with_system_update() {
            child
                .args([
                    "--exact",
-                    "bootstrap::config_loader_should_share_resolved_assets_with_system_update",
+                    "bootstrap::config::config_loader_should_share_resolved_assets_with_system_update",
                ])
                .env(CHILD_ENV, case)
                .env_remove("CPR_WEB_DIST_DIR");
@@ -267,11 +76,6 @@ fn config_loader_should_reject_missing_runtime_data_dir() {
    assert!(parse_config(&config).is_err());
 }

-#[test]
-fn config_loader_should_inject_connection_passwords_into_urls() {
-    parse_config(&valid_config()).expect("Store validates password injection into both URLs");
-}
-
 #[test]
 fn config_loader_should_apply_only_explicit_topology_overrides() {
    let invalid = valid_config()
@@ -292,7 +96,7 @@ fn config_loader_should_apply_only_explicit_topology_overrides() {
    let status = Command::new(std::env::current_exe().expect("current test executable"))
        .args([
            "--exact",
-            "bootstrap::config_loader_should_apply_only_explicit_topology_overrides",
+            "bootstrap::config::config_loader_should_apply_only_explicit_topology_overrides",
        ])
        .env(TOPOLOGY_CHILD_ENV, "1")
        .env("CPR_SERVER_HOST", "127.0.0.1")
@@ -374,7 +178,15 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
        gateway_host::load_config::<GatewayConfig>().expect("startup configuration");
        return;
    }
-    for case in ["normal", "unused", "missing"] {
+    for case in [
+        "normal",
+        "unused",
+        "missing",
+        "timezoneEmpty",
+        "timezoneInvalid",
+        "timezoneNull",
+        "timezoneType",
+    ] {
        let mut document = valid_config_document();
        if case == "unused" {
            document["openai"]["wire_profile"]["location"] = serde_json::json!(UNUSED_SECRET);
@@ -384,6 +196,14 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
                .unwrap()
                .remove("port");
        }
+        if case.starts_with("timezone") {
+            document["host"]["timezone"] = match case {
+                "timezoneEmpty" => serde_json::json!(""),
+                "timezoneInvalid" => serde_json::json!(UNUSED_SECRET),
+                "timezoneNull" => serde_json::json!(null),
+                _ => serde_json::json!(8),
+            };
+        }
        let directory = tempfile::tempdir().unwrap();
        fs::create_dir(directory.path().join("deploy")).unwrap();
        fs::write(
@@ -394,7 +214,7 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
        let output = Command::new(std::env::current_exe().unwrap())
            .args([
                "--exact",
-                "bootstrap::config_loader_should_report_startup_configuration_diagnostics",
+                "bootstrap::config::config_loader_should_report_startup_configuration_diagnostics",
                "--nocapture",
            ])
            .env(CHILD_ENV, "1")
@@ -404,7 +224,7 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
        let stderr = String::from_utf8_lossy(&output.stderr);
        assert_eq!(
            output.status.success(),
-            case != "missing",
+            case != "missing" && !case.starts_with("timezone"),
            "{case}: {stderr}"
        );
        match case {
@@ -413,6 +233,9 @@ fn config_loader_should_report_startup_configuration_diagnostics() {
                "{stderr}"
            ),
            "missing" => assert!(stderr.contains("host.listen.port"), "{stderr}"),
+            case if case.starts_with("timezone") => {
+                assert!(stderr.contains("host.timezone"), "{stderr}")
+            }
            _ => assert!(!stderr.contains("警告"), "{stderr}"),
        }
        assert!(!stderr.contains(UNUSED_SECRET), "{stderr}");
@@ -553,7 +376,7 @@ fn valid_config() -> String {
 }

 fn valid_config_document() -> serde_json::Value {
-    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载。
+    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载
    config::Config::builder()
        .add_source(config::File::from_str(
            &valid_config(),
@@ -580,3 +403,18 @@ fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), Stri
        .map_err(|error| error.to_string())?;
    Ok((config, directory))
 }
+
+#[test]
+fn deployment_timezone_defaults_and_valid_override_are_loaded() {
+    let mut document = valid_config_document();
+    document["host"].as_object_mut().unwrap().remove("timezone");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Shanghai");
+    document["host"]["timezone"] = serde_json::json!("Asia/Kathmandu");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Kathmandu");
+}
@@ -0,0 +1,5 @@
+//! 网关启动配置、命令行与服务组装的测试入口
+
+mod command;
+mod config;
+mod server;
@@ -0,0 +1,148 @@
+//! 验证服务组装为 HTTPS 代理探测传递自定义 CA
+
+use std::{fs, process::Command};
+
+#[tokio::test]
+async fn proxy_probe_should_use_provider_custom_ca_for_https_proxies() {
+    use gateway_admin::ports::proxy::ProxyProbe;
+    use gateway_core::account::OutboundProxy;
+    use gateway_host::proxy_probe::HttpProxyProbe;
+    use std::{sync::Arc, time::Duration};
+    use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+    use tokio_rustls::{
+        TlsAcceptor,
+        rustls::{
+            ServerConfig,
+            pki_types::{CertificateDer, PrivateKeyDer, pem::PemObject as _},
+        },
+    };
+
+    const CHILD_ENV: &str = "CPR_TEST_PROXY_TLS_DIRECTORY";
+    let Ok(directory) = std::env::var(CHILD_ENV) else {
+        let directory = tempfile::tempdir().unwrap();
+        generate_proxy_test_certificates(directory.path());
+        // 使用子进程隔离环境变量，避免并行测试读取到临时 CA 配置
+        for ca_env in ["CODEX_CA_CERTIFICATE", "SSL_CERT_FILE"] {
+            let mut child = Command::new(std::env::current_exe().unwrap());
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::server::proxy_probe_should_use_provider_custom_ca_for_https_proxies",
+                    "--nocapture",
+                ])
+                .env(CHILD_ENV, directory.path())
+                .env_remove("CODEX_CA_CERTIFICATE")
+                .env_remove("SSL_CERT_FILE")
+                .env(ca_env, directory.path().join("ca.pem"));
+            if ca_env == "CODEX_CA_CERTIFICATE" {
+                child.env(
+                    "SSL_CERT_FILE",
+                    directory.path().join("missing-fallback.pem"),
+                );
+            }
+            let output = child.output().unwrap();
+            assert!(
+                output.status.success(),
+                "{ca_env}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    provider_openai::ensure_rustls_provider();
+    let directory = std::path::Path::new(&directory);
+    let certificate = CertificateDer::from_pem_file(directory.join("server.pem")).unwrap();
+    let key = PrivateKeyDer::from_pem_file(directory.join("server.key")).unwrap();
+    let acceptor = TlsAcceptor::from(Arc::new(
+        ServerConfig::builder()
+            .with_no_client_auth()
+            .with_single_cert(vec![certificate], key)
+            .unwrap(),
+    ));
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+    let proxy =
+        OutboundProxy::parse(&format!("https://{}", listener.local_addr().unwrap())).unwrap();
+    let server = tokio::spawn(async move {
+        let (socket, _) = listener.accept().await.unwrap();
+        let mut stream = acceptor.accept(socket).await.unwrap();
+        let mut request = Vec::new();
+        while !request.ends_with(b"\r\n\r\n") {
+            assert!(request.len() < 8192);
+            request.push(stream.read_u8().await.unwrap());
+        }
+        assert!(request.starts_with(b"GET http://unresolvable.invalid/ip "));
+        let body = "{\"ip\":\"203.0.113.8\"}";
+        stream.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}", body.len()).as_bytes()).await.unwrap();
+        stream.shutdown().await.unwrap();
+    });
+    let probe = HttpProxyProbe::new("http://unresolvable.invalid/ip")
+        .with_client_builder(provider_openai::build_reqwest_client_with_custom_ca);
+    let result = probe.test(&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",
+    ]);
+}
@@ -1,8 +1,10 @@
+//! 网关组合根测试入口，检查源码模块纪律与冻结的文件边界
+
 mod architecture;
 mod bootstrap;

-// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界。
-// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护。
+// 组合根是否混入业务策略由代码审查判断，行数和标识符/注释关键词不能证明职责越界
+// 依赖 DAG、公开模块面和模块镜像继续由 architecture 检查，源码纪律由下方测试维护

 use std::{
    collections::BTreeSet,
@@ -18,7 +20,12 @@ fn app_tree_matches_frozen_terminal_manifest() {
    assert_eq!(
        rust_files(&root.join("src")),
        BTreeSet::from([
-            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("bootstrap/command.rs"),
+            PathBuf::from("bootstrap/config.rs"),
+            PathBuf::from("bootstrap/mod.rs"),
+            PathBuf::from("bootstrap/plugins.rs"),
+            PathBuf::from("bootstrap/server.rs"),
+            PathBuf::from("bootstrap/startup.rs"),
            PathBuf::from("lib.rs"),
            PathBuf::from("main.rs"),
        ]),
@@ -27,7 +34,10 @@ fn app_tree_matches_frozen_terminal_manifest() {
        rust_files(&root.join("tests")),
        BTreeSet::from([
            PathBuf::from("architecture.rs"),
-            PathBuf::from("bootstrap.rs"),
+            PathBuf::from("bootstrap/command.rs"),
+            PathBuf::from("bootstrap/config.rs"),
+            PathBuf::from("bootstrap/mod.rs"),
+            PathBuf::from("bootstrap/server.rs"),
            PathBuf::from("main.rs"),
        ]),
    );
@@ -1,17 +1,17 @@
 # Codex Proxy Plugin CLI

 `cpr-plugin` 校验并规范化作者清单、收集声明的资源，生成可安装归档及 SHA-256 校验文件。
-当前输出使用 `manifestVersion: 1`、`protocolVersion: 1` 和 SDK `0.1` 合同。
+输出合同与 [SDK 版本](../../crates/gateway-plugin/sdk/README.md)一致

 ## 安装

 从仓库根目录安装到本地工具目录：

 ```bash
-cargo install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
+cargo +1.97.0 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
 ```

-将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径。
+将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径；工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致

 ## 打包

@@ -26,26 +26,25 @@ cpr-plugin package \
  --output-dir /path/to/output
 ```

-资源映射相对于作者清单所在目录解析。输出包括完整插件 ID、版本和目标 triple 命名的 `.tar.gz` 及 `.sha256`；归档根目录直接包含 `plugin.json`、可执行文件和已声明资源，不包含开发依赖。
+资源映射相对于作者清单所在目录解析。输出包括完整插件 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)。
+作者清单的省略规则、能力版本和挂载阶段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)。
+CLI 与 SDK 的 `Manifest::from_author_slice`、`PluginBuilder::from_json` 共用规范化入口，归档只保留补全字段后的 `plugin.json`

-支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。完整开发示例在同级 `codex-proxy-plugins/examples/workbench` 仓库目录；本工具不负责源码构建、上传或启用插件。
+支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。
+完整开发示例在独立仓库 `codex-proxy-plugins` 的 `examples/workbench`，可通过[子模块](../../../docs/development.md#源码联调)检出；本工具不负责源码构建、上传或启用插件

 ### 图标资源

 在作者清单的 `icon` 中指定图标，并在 `resources` 中登记对应路径与 MIME 类型，配置方式见
 [SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算，
-无需额外命令参数；工具保留文件原始内容，宿主安装时验证图标内容与资源限制。
+无需额外命令参数；工具保留文件原始内容，宿主安装时验证图标内容与资源限制

 ## 开发

-Rust 包名为 `codex-proxy-plugin-cli`，位于宿主的 `backend` workspace，共享工具链、锁文件和检查规则；内部仅依赖 `gateway-plugin-sdk`。
+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
+cargo +1.97.0 run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
 RUST_MIN_STACK=16777216 cargo +1.97.0 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
 ```
@@ -1,3 +1,5 @@
+//! 插件打包命令行，校验输入资源并生成带摘要的平台归档
+
 use std::{
    collections::{BTreeMap, BTreeSet},
    fs::{self, File, OpenOptions},
@@ -1,3 +1,5 @@
+//! 插件打包命令行的参数、归档校验与输出行为测试
+
 use std::{
    collections::BTreeMap,
    fs::{self, File},
@@ -128,7 +130,7 @@ fn rejects_duplicate_resource_prefixes() {
 }

 #[test]
-fn packages_only_generated_resources_with_v3_metadata() {
+fn packages_only_generated_resources_with_current_metadata() {
    assert_packaged_resources("assets/icon.png", "image/png", b"png");
 }

@@ -237,7 +239,7 @@ fn assert_packaged_resources(icon_path: &str, icon_mime: &str, icon: &[u8]) {

 fn source_manifest() -> &'static [u8] {
    br#"{
-      "manifestVersion":1,
+      "manifestVersion":2,
      "name":"request-workbench",
      "displayName":"Request Workbench",
      "publisher":"codex-proxy",
@@ -248,10 +250,10 @@ fn source_manifest() -> &'static [u8] {
      "main":"bin/plugin",
      "runtime":"trustedProcess",
      "contributes":{
-        "middleware":{"stages":["request"],"inputFormats":["openai"],"outputFormats":["openai"]},
+        "middleware":{"version":4,"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"}
    }"#
@@ -21,6 +21,7 @@ futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
 heck = "0.5.0"
 hex = "0.4.3"
+hkdf = "0.13.0"
 rand_core = { version = "0.6.4", features = ["getrandom"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = { version = "1.0.150", features = ["arbitrary_precision", "preserve_order"] }
@@ -36,6 +37,9 @@ chrono-tz = "0.10"
 tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }

 [dev-dependencies]
+prettyplease = "0.3"
+quote = "1"
+syn = { version = "3", features = ["full", "visit-mut"] }
 tempfile = "3"
 tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "test-util"] }

@@ -1,4 +1,4 @@
-//! 备份纯策略与 Worker 任务。
+//! 备份纯策略与 Worker 任务

 pub mod policy;
 pub mod task;
@@ -1,6 +1,6 @@
-//! 备份纯策略：Cron 推进与保留候选。
+//! 备份纯策略：Cron 推进与保留候选
 //!
-//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集。
+//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集

 use std::str::FromStr;

@@ -10,10 +10,11 @@ use cron::Schedule;

 use crate::model::backup::{BackupError, BackupRecord, BackupStatus, code};

-/// 向历史回溯的最大范围（分钟）。覆盖 Feb 29 + 特定星期等罕见组合的最长间隔。
+/// 向历史回溯的最大范围（分钟）
+/// 覆盖 Feb 29 + 特定星期等罕见组合的最长间隔
 const MAX_BACKDATE_MINUTES: i64 = 40 * 366 * 24 * 60;

-/// 已解析并校验的备份计划。
+/// 已解析并校验的备份计划
 #[derive(Debug, Clone)]
 pub struct BackupSchedule {
    schedule: Schedule,
@@ -21,43 +22,44 @@ pub struct BackupSchedule {
 }

 impl BackupSchedule {
-    /// 解析并校验 5 段 Cron 与 IANA 时区。
+    /// 按部署时区解析并校验 5 段 Cron
    ///
    /// # Errors
    ///
-    /// Cron 非法或时区不是 IANA 名称时返回 [`BackupError`]。
-    pub fn parse(cron_expression: &str, schedule_timezone: &str) -> Result<Self, BackupError> {
+    /// Cron 非法时返回 [`BackupError`]
+    pub fn parse(
+        cron_expression: &str,
+        timezone: gateway_core::time::DeploymentTimeZone,
+    ) -> Result<Self, BackupError> {
        let expression = format!("0 {cron_expression}");
        let schedule = Schedule::from_str(&expression).map_err(|_| {
            BackupError::new(code::INVALID_CRON, "Cron 表达式必须是 5 段格式".to_owned())
        })?;
-        let timezone = schedule_timezone.parse::<Tz>().map_err(|_| {
-            BackupError::new(code::INVALID_TIMEZONE, "时区必须是 IANA 名称".to_owned())
-        })?;
-        Ok(Self { schedule, timezone })
+        Ok(Self {
+            schedule,
+            timezone: timezone.iana(),
+        })
    }

-    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间。
+    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间
    ///
    /// 若过去 `MAX_BACKDATE_MINUTES` 内没有任何触发（极罕见的稀疏计划或超长停机），
-    /// 返回 `None`，调用方不应为历史点补任务。
+    /// 返回 `None`，调用方不应为历史点补任务
    #[must_use]
    pub fn last_firing_at_or_before(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
        let high_min = at.timestamp().div_euclid(60);
        let low_min = high_min.saturating_sub(MAX_BACKDATE_MINUTES);

-        // 检查窗口内是否存在触发；不存在则直接返回 None。
+        // 检查窗口内是否存在触发；不存在则直接返回 None
        let low_instant = instant(low_min, self.timezone)?;
        if self
-            .schedule
-            .after(&low_instant)
-            .next()
+            .next_after(low_instant.to_utc())
            .is_none_or(|firing| firing.timestamp() > high_min * 60 + 59)
        {
            return None;
        }

-        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)。
+        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)
        let mut lo = low_min;
        let mut hi = high_min;
        while lo < hi {
@@ -76,54 +78,56 @@ impl BackupSchedule {
            .and_then(|firing| Utc.timestamp_opt(firing * 60, 0).single())
    }

-    /// 返回第一个严格晚于 `at` 的触发时间。
+    /// 返回第一个严格晚于 `at` 的触发时间
    #[must_use]
    pub fn next_after(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
-        let local = at.with_timezone(&self.timezone);
-        self.schedule
-            .after(&local)
-            .next()
-            .map(|firing| firing.with_timezone(&Utc))
+        let local = at.with_timezone(&self.timezone).naive_local().and_utc();
+        self.schedule.after(&local).find_map(|firing| {
+            let instant = self
+                .timezone
+                .from_local_datetime(&firing.naive_utc())
+                .earliest()?
+                .to_utc();
+            (instant > at).then_some(instant)
+        })
    }

-    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索。
+    /// `after(u 分钟)` 返回的第一个触发时间（分钟索引），用于二分搜索
    fn firing_after(&self, minute_index: i64) -> Option<i64> {
-        let instant = instant(minute_index, self.timezone)?;
-        self.schedule
-            .after(&instant)
-            .next()
+        let instant = instant(minute_index, self.timezone)?.to_utc();
+        self.next_after(instant)
            .map(|firing| firing.timestamp().div_euclid(60))
    }
 }

-/// 构造指定分钟索引（UTC epoch 分钟）在目标时区下的 `DateTime`。
+/// 构造指定分钟索引（UTC epoch 分钟）在目标时区下的 `DateTime`
 fn instant(minute_index: i64, timezone: Tz) -> Option<DateTime<Tz>> {
    timezone.timestamp_opt(minute_index * 60, 0).single()
 }

-/// 一条记录被纳入删除流程的原因。
+/// 一条记录被纳入删除流程的原因
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RetentionReason {
-    /// 超过 `retention_days`。
+    /// 超过 `retention_days`
    Days,
-    /// 超过 `retention_count`。
+    /// 超过 `retention_count`
    Count,
 }

-/// 保留决策。
+/// 保留决策
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RetentionDecision {
    pub record_id: String,
    pub reason: RetentionReason,
 }

-/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录。
+/// 从按完成时间倒序的 completed 计划备份中决定纳入删除流程的记录
 ///
 /// 自动保留规则：
-/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理。
-/// - 自动计划备份满足任一启用阈值即可进入删除。
-/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）。
-/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理。
+/// - `retentionDays = 0` 时不按天数清理；`retentionCount = 0` 时不按份数清理
+/// - 自动计划备份满足任一启用阈值即可进入删除
+/// - 无论阈值如何，至少保留最近一个成功的计划备份（倒序下标 0）
+/// - 手动备份不进入本规则；手工/计划记录各自的 `expires_at` 由到期扫描处理
 #[must_use]
 pub fn decide_retention(
    retention_days: u32,
@@ -136,7 +140,7 @@ pub fn decide_retention(
        if record.status != BackupStatus::Completed {
            continue;
        }
-        // 最近一个成功的计划备份永远保留。
+        // 最近一个成功的计划备份永远保留
        if index == 0 {
            continue;
        }
@@ -1,7 +1,8 @@
-//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理。
+//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理
 //!
-//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat。长时间
-//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭。
+//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat
+//! 长时间
+//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭

 use std::sync::Arc;
 use std::time::Duration;
@@ -16,8 +17,8 @@ use tracing::{info, warn};

 use crate::{
    model::backup::{
-        BackupError, BackupObjectMetadata, BackupRecord, BackupStatus, BackupStorageConfig,
-        BackupTriggerKind, build_backup_seed, code,
+        BackupError, BackupObjectMetadata, BackupRecord, BackupStatus, BackupStatusTransition,
+        BackupStorageConfig, BackupTriggerKind, build_backup_seed, code,
    },
    ports::backup::{
        BackupObjectStorePort, BackupRepository, DatabaseDumpPort, DumpRequest,
@@ -27,30 +28,31 @@ use crate::{

 impl From<BackupError> for WorkerTaskError {
    fn from(error: BackupError) -> Self {
-        WorkerTaskError::safe(error.message())
+        WorkerTaskError::safe(error.message()).with_source(error)
    }
 }

 use super::policy::{BackupSchedule, decide_retention};

-/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待。
+/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待
 const BACKUP_LOOP_INTERVAL: Duration = Duration::from_secs(30);
-/// 每个循环最多执行的保留删除数量。
+/// 每个循环最多执行的保留删除数量
 const RETENTION_BATCH_SIZE: usize = 10;
-/// 保留扫描一次读取的 completed 计划备份上限。
+/// 保留扫描一次读取的 completed 计划备份上限
 const RETENTION_SCAN_LIMIT: u32 = 1000;
-/// 每个循环最多完成的待删除记录数量。
+/// 每个循环最多完成的待删除记录数量
 const PENDING_DELETION_BATCH: u32 = 20;

-/// 备份 Daemon 任务。
+/// 备份 Daemon 任务
 pub struct BackupTask {
+    timezone: gateway_core::time::DeploymentTimeZone,
    repository: Arc<dyn BackupRepository>,
    dump: Arc<dyn DatabaseDumpPort>,
    object_store: Arc<dyn BackupObjectStorePort>,
 }

 impl BackupTask {
-    /// 组合仓储、导出器与对象存储适配器。
+    /// 组合仓储、导出器与对象存储适配器
    #[must_use]
    pub fn new(
        repository: Arc<dyn BackupRepository>,
@@ -58,11 +60,18 @@ impl BackupTask {
        object_store: Arc<dyn BackupObjectStorePort>,
    ) -> Self {
        Self {
+            timezone: Default::default(),
            repository,
            dump,
            object_store,
        }
    }
+
+    #[must_use]
+    pub fn with_timezone(mut self, timezone: gateway_core::time::DeploymentTimeZone) -> Self {
+        self.timezone = timezone;
+        self
+    }
 }

 impl DaemonTask for BackupTask {
@@ -86,13 +95,13 @@ impl BackupTask {
        }
    }

-    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理。
+    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理
    ///
-    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用。
+    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用
    ///
    /// # Errors
    ///
-    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]。
+    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]
    pub async fn run_cycle(&self, cancellation: &CancellationToken) -> Result<(), WorkerTaskError> {
        if cancellation.is_cancelled() {
            return Ok(());
@@ -105,29 +114,52 @@ impl BackupTask {
        Ok(())
    }

-    /// 推进到期计划并幂等插入 scheduled 任务。
+    /// 推进到期计划并幂等插入 scheduled 任务
    async fn advance_schedule(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
        let settings = self.repository.load_settings().await.map_err(repo_error)?;
        if !settings.schedule_enabled {
            return Ok(());
        }
        let cron = settings.cron_expression.as_deref().unwrap_or_default();
-        let timezone = settings.schedule_timezone.as_deref().unwrap_or_default();
-        if cron.is_empty() || timezone.is_empty() {
+        let timezone = self.timezone.name();
+        if cron.is_empty() {
            return Ok(());
        }
-        let schedule = BackupSchedule::parse(cron, timezone)
-            .map_err(|_| WorkerTaskError::safe("backup schedule is invalid"))?;
+        let schedule = BackupSchedule::parse(cron, self.timezone).map_err(|source| {
+            WorkerTaskError::safe("backup schedule is invalid").with_source(source)
+        })?;

+        if settings.schedule_timezone.as_deref() != Some(timezone) {
+            // 时区切换只初始化未来游标，不把旧时区计划当作应补跑任务
+            if let Some(next_run_at) = schedule.next_after(now) {
+                self.repository
+                    .advance_schedule_cursor(
+                        next_run_at,
+                        cron,
+                        settings.schedule_timezone.as_deref(),
+                        settings.next_run_at,
+                        timezone,
+                    )
+                    .await
+                    .map_err(repo_error)?;
+            }
+            return Ok(());
+        }
        let due = match settings.next_run_at {
            Some(next_run_at) if next_run_at <= now => true,
            Some(_) => false,
            None => {
-                // 刚启用计划但尚无游标：直接初始化。
+                // 刚启用计划但尚无游标：直接初始化
                if let Some(next_run_at) = schedule.next_after(now) {
                    let _ = self
                        .repository
-                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .advance_schedule_cursor(
+                            next_run_at,
+                            cron,
+                            Some(timezone),
+                            settings.next_run_at,
+                            timezone,
+                        )
                        .await
                        .map_err(repo_error)?;
                }
@@ -141,11 +173,17 @@ impl BackupTask {
        let scheduled_at = match schedule.last_firing_at_or_before(now) {
            Some(scheduled_at) => scheduled_at,
            None => {
-                // 无法从计划推导最近到期时间：推进游标避免反复触发。
+                // 无法从计划推导最近到期时间：推进游标避免反复触发
                if let Some(next_run_at) = schedule.next_after(now) {
                    let _ = self
                        .repository
-                        .advance_schedule_cursor(next_run_at, cron, timezone)
+                        .advance_schedule_cursor(
+                            next_run_at,
+                            cron,
+                            Some(timezone),
+                            settings.next_run_at,
+                            timezone,
+                        )
                        .await
                        .map_err(repo_error)?;
                }
@@ -168,25 +206,24 @@ impl BackupTask {
        .map_err(infra_error)?;
        let inserted = self
            .repository
-            .insert_scheduled_record(seed)
+            .insert_scheduled_record(
+                seed,
+                schedule.next_after(now),
+                cron,
+                timezone,
+                settings.next_run_at,
+            )
            .await
            .map_err(repo_error)?;
        if inserted {
            info!(scheduled_at = %scheduled_at, "计划备份任务已创建");
        } else {
-            warn!(scheduled_at = %scheduled_at, "计划时间点冲突，跳过并推进游标");
-        }
-        if let Some(next_run_at) = schedule.next_after(now) {
-            let _ = self
-                .repository
-                .advance_schedule_cursor(next_run_at, cron, timezone)
-                .await
-                .map_err(repo_error)?;
+            warn!(scheduled_at = %scheduled_at, "计划已变化或存在冲突，本轮未创建任务");
        }
        Ok(())
    }

-    /// 恢复中间状态（dumping/uploading/deleting）。
+    /// 恢复中间状态（dumping/uploading/deleting）
    async fn recover_intermediate(
        &self,
        cancellation: &CancellationToken,
@@ -206,7 +243,7 @@ impl BackupTask {
        Ok(())
    }

-    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败。
+    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败
    async fn recover_dumping(
        &self,
        record: &BackupRecord,
@@ -224,8 +261,7 @@ impl BackupTask {
                    .repository
                    .transition_status(
                        &record.id,
-                        BackupStatus::Dumping,
-                        BackupStatus::Uploading,
+                        status_transition(BackupStatus::Dumping, BackupStatus::Uploading)?,
                        update,
                        now,
                    )
@@ -245,7 +281,6 @@ impl BackupTask {
                .await?;
            }
            None => {
-                let _ = self.dump.cleanup_staging(&record.id).await;
                self.fail_task(record, code::PG_DUMP_FAILED, "导出进程中断，暂存归档不完整")
                    .await?;
            }
@@ -253,7 +288,7 @@ impl BackupTask {
        Ok(())
    }

-    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败。
+    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败
    async fn recover_uploading(
        &self,
        record: &BackupRecord,
@@ -271,16 +306,20 @@ impl BackupTask {
            && record.sha256.as_deref() == Some(remote.sha256.as_str())
        {
            let now = Utc::now();
-            self.repository
+            if self
+                .repository
                .transition_status(
                    &record.id,
-                    BackupStatus::Uploading,
-                    BackupStatus::Completed,
+                    status_transition(BackupStatus::Uploading, BackupStatus::Completed)?,
                    StatusTransitionUpdate::default(),
                    now,
                )
                .await
-                .map_err(repo_error)?;
+                .map_err(repo_error)?
+                .is_some()
+            {
+                self.cleanup_staging(&record.id).await;
+            }
            return Ok(());
        }
        match self.dump.inspect_staging(&record.id).await? {
@@ -306,7 +345,7 @@ impl BackupTask {
        }
    }

-    /// 完成待删除记录（deleting → DeleteObject → 硬删除）。
+    /// 完成待删除记录（deleting → DeleteObject → 硬删除）
    async fn finish_pending_deletions(&self) -> Result<(), WorkerTaskError> {
        let settings = self.repository.load_settings().await.map_err(repo_error)?;
        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
@@ -333,7 +372,7 @@ impl BackupTask {
        Ok(())
    }

-    /// 领取一个 queued 任务并执行导出、上传与远端校验。
+    /// 领取一个 queued 任务并执行导出、上传与远端校验
    async fn process_next_task(
        &self,
        cancellation: &CancellationToken,
@@ -358,7 +397,7 @@ impl BackupTask {
        Ok(())
    }

-    /// 执行单个任务；内部处理全部状态迁移。
+    /// 执行单个任务；内部处理全部状态迁移
    async fn execute_task(
        &self,
        record: &BackupRecord,
@@ -392,7 +431,7 @@ impl BackupTask {
            }
        };

-        // dumping → uploading，持久化 size/sha256。
+        // dumping → uploading，持久化 size/sha256
        let update = StatusTransitionUpdate {
            size_bytes: Some(artifact.size_bytes),
            sha256: Some(artifact.sha256.clone()),
@@ -402,8 +441,7 @@ impl BackupTask {
            .repository
            .transition_status(
                &record.id,
-                BackupStatus::Dumping,
-                BackupStatus::Uploading,
+                status_transition(BackupStatus::Dumping, BackupStatus::Uploading)?,
                update,
                now,
            )
@@ -421,12 +459,10 @@ impl BackupTask {
            now,
            cancellation,
        )
-        .await?;
-        let _ = self.dump.cleanup_staging(&record.id).await;
-        Ok(())
+        .await
    }

-    /// 上传 + 远端校验，内部完成终态迁移。
+    /// 上传 + 远端校验，内部完成终态迁移
    async fn upload_and_verify(
        &self,
        record: &BackupRecord,
@@ -455,11 +491,13 @@ impl BackupTask {
            )
            .await
        {
-            let _ = store.delete_object(&config, &record.object_key).await;
-            self.fail_task(
+            self.fail_uploaded_task(
                record,
-                error.code(),
-                format!("上传到对象存储失败：{}", error.message()),
+                &config,
+                BackupError::new(
+                    error.code(),
+                    format!("上传到对象存储失败：{}", error.message()),
+                ),
            )
            .await?;
            return Ok(());
@@ -471,8 +509,7 @@ impl BackupTask {
                    .repository
                    .transition_status(
                        &record.id,
-                        BackupStatus::Uploading,
-                        BackupStatus::Completed,
+                        status_transition(BackupStatus::Uploading, BackupStatus::Completed)?,
                        StatusTransitionUpdate::default(),
                        Utc::now(),
                    )
@@ -485,6 +522,7 @@ impl BackupTask {
                        size_bytes,
                        "备份完成"
                    );
+                    self.cleanup_staging(&record.id).await;
                }
            }
            Ok(Some(remote)) => {
@@ -497,16 +535,19 @@ impl BackupTask {
                    sha256_matches,
                    "备份远端对象校验不一致"
                );
-                let _ = store.delete_object(&config, &record.object_key).await;
-                self.fail_task(
+                self.fail_uploaded_task(
                    record,
-                    code::REMOTE_VERIFICATION_FAILED,
-                    match (size_matches, sha256_matches) {
-                        (false, true) => "远端对象大小不一致",
-                        (true, false) => "远端对象 sha256 校验值不一致",
-                        (false, false) => "远端对象大小和 sha256 校验值均不一致",
-                        (true, true) => "远端对象校验状态异常",
-                    },
+                    &config,
+                    BackupError::new(
+                        code::REMOTE_VERIFICATION_FAILED,
+                        match (size_matches, sha256_matches) {
+                            (false, true) => "远端对象大小不一致",
+                            (true, false) => "远端对象 sha256 校验值不一致",
+                            (false, false) => "远端对象大小和 sha256 校验值均不一致",
+                            (true, true) => "远端对象校验状态异常",
+                        }
+                        .to_owned(),
+                    ),
                )
                .await?;
            }
@@ -520,11 +561,13 @@ impl BackupTask {
                .await?;
            }
            Err(error) => {
-                let _ = store.delete_object(&config, &record.object_key).await;
-                self.fail_task(
+                self.fail_uploaded_task(
                    record,
-                    error.code(),
-                    format!("远端对象校验失败：{}", error.message()),
+                    &config,
+                    BackupError::new(
+                        error.code(),
+                        format!("远端对象校验失败：{}", error.message()),
+                    ),
                )
                .await?;
            }
@@ -532,7 +575,25 @@ impl BackupTask {
        Ok(())
    }

-    /// 把活跃任务写入失败终态并清理暂存。
+    /// 清理失败并入原终态，后续清理沿用备份记录的到期策略
+    async fn fail_uploaded_task(
+        &self,
+        record: &BackupRecord,
+        config: &BackupStorageConfig,
+        mut error: BackupError,
+    ) -> Result<(), WorkerTaskError> {
+        if let Err(cleanup) = self
+            .object_store
+            .delete_object(config, &record.object_key)
+            .await
+        {
+            error =
+                error.with_cleanup_failure("DeleteObject", &cleanup, record.expires_at.is_some());
+        }
+        self.fail_task(record, error.code(), error.message()).await
+    }
+
+    /// 把活跃任务写入失败终态并清理暂存
    async fn fail_task(
        &self,
        record: &BackupRecord,
@@ -555,18 +616,29 @@ impl BackupTask {
        };
        let _ = self
            .repository
-            .transition_status(&record.id, record.status, BackupStatus::Failed, update, now)
+            .transition_status(
+                &record.id,
+                status_transition(record.status, BackupStatus::Failed)?,
+                update,
+                now,
+            )
            .await
            .map_err(repo_error)?;
-        let _ = self.dump.cleanup_staging(&record.id).await;
+        self.cleanup_staging(&record.id).await;
        Ok(())
    }

-    /// 执行一小批到期保留清理：先处理 `expires_at` 已到期的记录，再按天数/份数清理计划备份。
+    async fn cleanup_staging(&self, backup_id: &str) {
+        if let Err(error) = self.dump.cleanup_staging(backup_id).await {
+            warn!(backup_id, error = %error, "清理备份暂存失败");
+        }
+    }
+
+    /// 执行一小批到期保留清理：先处理 `expires_at` 已到期的记录，再按天数/份数清理计划备份
    async fn run_retention_batch(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
        let settings = self.repository.load_settings().await.map_err(repo_error)?;

-        // 1. expires_at 已到期的记录（手动或计划）无条件进入删除。
+        // 1. expires_at 已到期的记录（手动或计划）无条件进入删除
        let expired = self
            .repository
            .list_expired_records(RETENTION_BATCH_SIZE as u32)
@@ -584,7 +656,7 @@ impl BackupTask {
            self.finalize_deletion(&record).await?;
        }

-        // 2. 计划备份按 retentionDays / retentionCount 清理。
+        // 2. 计划备份按 retentionDays / retentionCount 清理
        let records = self
            .repository
            .list_scheduled_completed_desc(RETENTION_SCAN_LIMIT)
@@ -610,7 +682,7 @@ impl BackupTask {
        Ok(())
    }

-    /// 对已进入 deleting 的记录执行对象删除并硬删除记录行。
+    /// 对已进入 deleting 的记录执行对象删除并硬删除记录行
    async fn finalize_deletion(&self, record: &BackupRecord) -> Result<(), WorkerTaskError> {
        let settings = self.repository.load_settings().await.map_err(repo_error)?;
        let Some(config) = BackupStorageConfig::from_settings(&settings) else {
@@ -639,10 +711,18 @@ fn classify_dump_error(error: BackupError) -> (&'static str, &'static str) {
    }
 }

+fn status_transition(
+    from: BackupStatus,
+    to: BackupStatus,
+) -> Result<BackupStatusTransition, WorkerTaskError> {
+    BackupStatusTransition::try_new(from, to)
+        .ok_or_else(|| WorkerTaskError::safe("backup status transition is invalid"))
+}
+
 fn repo_error(error: crate::ports::store::AdminStoreError) -> WorkerTaskError {
-    WorkerTaskError::safe(format!("backup store failed: {error}"))
+    WorkerTaskError::safe("backup store failed").with_source(error)
 }

 fn infra_error(error: BackupError) -> WorkerTaskError {
-    WorkerTaskError::safe(error.message())
+    WorkerTaskError::safe(error.message()).with_source(error)
 }
@@ -1,8 +1,9 @@
-//! 容量熔断冻结的恢复编排：到期探测、失败顺延与自适应并发下调。
+//! 容量熔断冻结的恢复编排：到期探测、失败顺延与自适应并发下调
 //!
 //! 冻结事实保存在可丢失的 Redis 冷却中，本服务只组合 Admin 端口：
 //! 观测（`AccountRuntimeStore`）、探测（`AccountsService`）与写回
-//! （原子降低并发 / 按冻结代次结束探测）。旧观测不会覆盖管理员操作。
+//! （原子降低并发 / 按冻结代次结束探测）
+//! 旧观测不会覆盖管理员操作

 use std::collections::BTreeMap;
 use std::sync::Arc;
@@ -22,21 +23,21 @@ use crate::model::{MutationActor, MutationContext};
 use crate::ports::store::{AccountRuntimeStore, AccountStore, SettingsStore};
 use crate::use_case::accounts::AccountsService;

-/// 自适应并发下调保留系数：下调到观测在途峰值的 80%。
+/// 自适应并发下调保留系数：下调到观测在途峰值的 80%
 const ADAPTIVE_CONCURRENCY_FACTOR: f64 = 0.8;
-/// 自适应并发下限：过低的并发让账号几乎不可用，宁可保持冻结。
+/// 自适应并发下限：过低的并发让账号几乎不可用，宁可保持冻结
 const ADAPTIVE_CONCURRENCY_FLOOR: u32 = 2;
-/// worker 周期；冷却观测与探测都依赖该节奏。
+/// worker 周期；冷却观测与探测都依赖该节奏
 pub const FREEZE_RECOVERY_INTERVAL: Duration = Duration::from_secs(30);
 pub const FREEZE_RECOVERY_WORKER_OWNER: &str = "account-freeze-recovery";
 pub const WORKER_INITIAL_BACKOFF: Duration = Duration::from_secs(1);
 pub const WORKER_MAXIMUM_BACKOFF: Duration = Duration::from_secs(60);
 pub const WORKER_LEASE_TTL: Duration = Duration::from_secs(15 * 60);
 pub const WORKER_LEASE_RENEWAL: Duration = Duration::from_secs(5 * 60);
-/// 系统审计上下文的固定请求 ID；账号并发更新审计由此溯源到自动冻结编排。
+/// 系统审计上下文的固定请求 ID；账号并发更新审计由此溯源到自动冻结编排
 const SYSTEM_REQUEST_ID: &str = "account-freeze-recovery";

-/// 冻结恢复所需的管理端口组合。
+/// 冻结恢复所需的管理端口组合
 #[derive(Clone)]
 pub struct FreezeRecoveryDeps {
    pub accounts: Arc<dyn AccountsService>,
@@ -61,17 +62,17 @@ impl FreezeRecoveryTask {
        }
    }

-    /// 读取冻结策略；读取或校验失败跳过本轮，不能把未知配置当作允许解冻。
+    /// 读取冻结策略；读取或校验失败跳过本轮，不能把未知配置当作允许解冻
    async fn freeze_policy(&self) -> Option<gateway_core::provider_ports::ProviderFreezePolicy> {
        let settings = self.deps.settings.load_runtime_settings().await.ok()?;
        gateway_core::provider_ports::ProviderFreezePolicy::try_new(
-            settings.account_auto_freeze_enabled,
-            settings.account_auto_freeze_threshold,
-            settings.account_auto_freeze_window_seconds,
-            settings.account_auto_freeze_duration_seconds,
-            settings.account_auto_freeze_probe_enabled,
-            settings.account_auto_freeze_probe_model,
-            settings.account_auto_freeze_adaptive_concurrency,
+            settings.values.account_auto_freeze_enabled,
+            settings.values.account_auto_freeze_threshold,
+            settings.values.account_auto_freeze_window_seconds,
+            settings.values.account_auto_freeze_duration_seconds,
+            settings.values.account_auto_freeze_probe_enabled,
+            settings.values.account_auto_freeze_probe_model,
+            settings.values.account_auto_freeze_adaptive_concurrency,
        )
        .ok()
    }
@@ -95,7 +96,7 @@ impl FreezeRecoveryTask {
    }

    /// 对冻结中的账号执行自适应并发下调：目标为观测在途峰值的 80%（下限 2），
-    /// 只降不升；未观测到峰值证据的账号保持现状。
+    /// 只降不升；未观测到峰值证据的账号保持现状
    async fn adapt_concurrency_limits(
        &self,
        freezes: &BTreeMap<String, AccountFreeze>,
@@ -146,7 +147,7 @@ impl FreezeRecoveryTask {
            .ok()
    }

-    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束。
+    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束
    async fn recover_due_freezes(
        &self,
        freezes: &BTreeMap<String, AccountFreeze>,
@@ -179,14 +180,14 @@ impl FreezeRecoveryTask {
            return;
        };
        if !item.account.enabled {
-            // 停用账号没有自动恢复意义；解冻交给管理员手动恢复。
+            // 停用账号没有自动恢复意义；解冻交给管理员手动恢复
            return;
        }
        let Ok(account) = ProviderAccountId::new(account_id.to_owned()) else {
            return;
        };
        let Some(model) = self.resolve_probe_model(&account, policy).await else {
-            // 没有可用探测模型时按失败处理，顺延冻结等待下一轮。
+            // 没有可用探测模型时按失败处理，顺延冻结等待下一轮
            self.postpone(&account, freeze, policy).await;
            return;
        };
@@ -218,7 +219,7 @@ impl FreezeRecoveryTask {
        }
    }

-    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号。
+    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号
    async fn postpone(
        &self,
        account: &ProviderAccountId,
@@ -281,7 +282,7 @@ impl ScheduledTask for FreezeRecoveryTask {
    }
 }

-/// 自适应目标并发：观测峰值 × 0.8 向下取整，下限 2；无证据（峰值为 0）不调整。
+/// 自适应目标并发：观测峰值 × 0.8 向下取整，下限 2；无证据（峰值为 0）不调整
 fn adaptive_target(peak_in_flight: u32) -> Option<u32> {
    if peak_in_flight == 0 {
        return None;
@@ -290,7 +291,7 @@ fn adaptive_target(peak_in_flight: u32) -> Option<u32> {
    Some(scaled.max(ADAPTIVE_CONCURRENCY_FLOOR))
 }

-/// 消耗连接测试事件流并返回是否以 `Completed` 终止。
+/// 消耗连接测试事件流并返回是否以 `Completed` 终止
 async fn drain_probe(mut events: crate::model::accounts::AccountConnectionTestEventStream) -> bool {
    let mut completed = false;
    while let Some(event) = events.next().await {
@@ -1,6 +1,6 @@
-//! 管理控制面的语义模型、用例与外部能力端口。
+//! 管理控制面的语义模型、用例与外部能力端口
 //!
-//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。
+//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现

 use std::{fmt, path::Path, sync::Arc, time::Duration};

@@ -20,6 +20,7 @@ pub mod backup;
 pub mod freeze_recovery;
 pub mod model;
 pub mod ports;
+pub mod public_service;
 mod use_case;
 pub use use_case::plugins::{PluginDistributionPorts, PluginManagementService, PluginsService};

@@ -34,7 +35,7 @@ pub use use_case::{
    client_keys::ClientKeyService,
    credentials::{CredentialsService, ProviderCredentials},
    import_tasks::ImportTasksService,
-    observability::ObservabilityService,
+    observability::{ObservabilityService, ProviderUsageBillingProjector},
    proxies::ProxiesService,
    settings::SettingsService,
    system::SystemService,
@@ -69,7 +70,7 @@ const WEAK_ADMIN_PASSWORDS: &[&str] = &[
 const BACKUP_WORKER_OWNER: &str = "backup";
 const DEFAULT_CLIENT_SESSION_TTL_MINUTES: u64 = 24 * 60;

-/// 只用于首次幂等创建默认管理员的启动密码。
+/// 只用于首次幂等创建默认管理员的启动密码
 #[derive(Clone, Deserialize)]
 #[serde(transparent)]
 pub struct InitialAdminPassword(SecretString);
@@ -99,15 +100,21 @@ impl fmt::Debug for InitialAdminPassword {
    }
 }

-/// 管理控制面的启动配置。
+/// 管理控制面的启动配置
 #[derive(Clone, Deserialize, PartialEq, Eq)]
 pub struct AdminConfig {
    pub session_ttl_minutes: u64,
+    #[serde(default = "default_absolute_session_ttl_minutes")]
+    pub session_absolute_ttl_minutes: u64,
    pub default_username: String,
    pub default_password: InitialAdminPassword,
 }

-/// Client 登录域的通用启动配置。
+fn default_absolute_session_ttl_minutes() -> u64 {
+    30 * 24 * 60
+}
+
+/// Client 登录域的通用启动配置
 #[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
 pub struct ClientConfig {
    pub session_ttl_minutes: u64,
@@ -122,11 +129,11 @@ impl Default for ClientConfig {
 }

 impl ClientConfig {
-    /// 校验 Client session TTL；当前配置不含相对路径。
+    /// 校验 Client session TTL；当前配置不含相对路径
    ///
    /// # Errors
    ///
-    /// 会话有效期为零或无法安全换算时返回错误。
+    /// 会话有效期为零或无法安全换算时返回错误
    pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
        if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
            return Err(AdminConfigError::InvalidField("client.session_ttl_minutes"));
@@ -136,11 +143,11 @@ impl ClientConfig {
 }

 impl AdminConfig {
-    /// 校验 Admin-owned 字段；当前配置不含相对路径。
+    /// 校验 Admin-owned 字段；当前配置不含相对路径
    ///
    /// # Errors
    ///
-    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误。
+    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误
    pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
        if self.default_username.trim().is_empty()
            || self.default_username.chars().any(char::is_control)
@@ -150,6 +157,13 @@ impl AdminConfig {
        if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
            return Err(AdminConfigError::InvalidField("admin.session_ttl_minutes"));
        }
+        if self.session_absolute_ttl_minutes == 0
+            || i64::try_from(self.session_absolute_ttl_minutes).is_err()
+        {
+            return Err(AdminConfigError::InvalidField(
+                "admin.session_absolute_ttl_minutes",
+            ));
+        }
        let password = self.default_password.expose().trim();
        if password.len() < MINIMUM_INITIAL_PASSWORD_BYTES
            || password.contains('$')
@@ -166,13 +180,17 @@ impl fmt::Debug for AdminConfig {
        formatter
            .debug_struct("AdminConfig")
            .field("session_ttl_minutes", &self.session_ttl_minutes)
+            .field(
+                "session_absolute_ttl_minutes",
+                &self.session_absolute_ttl_minutes,
+            )
            .field("default_username", &self.default_username)
            .field("default_password", &"[REDACTED]")
            .finish()
    }
 }

-/// Admin-owned 启动配置错误；不回显任何配置值。
+/// Admin-owned 启动配置错误；不回显任何配置值
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum AdminConfigError {
    #[error("配置字段 `{0}` 不合法")]
@@ -181,11 +199,13 @@ pub enum AdminConfigError {
    WeakInitialPassword,
 }

-/// API 持有的管理资源能力集合。
+/// API 持有的管理资源能力集合
 ///
-/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块。
+/// 字段全部私有；调用方经 accessor 直接调用能力，不需要命名内部 `use_case` 模块
 #[derive(Clone)]
 pub struct AdminServices {
+    timezone: gateway_core::time::DeploymentTimeZone,
+    public_services: Arc<public_service::Registry>,
    plugins: Arc<PluginsService>,
    plugin_management: Arc<PluginManagementService>,
    proxies: Arc<dyn ProxiesService>,
@@ -199,12 +219,22 @@ pub struct AdminServices {
    settings: Arc<dyn SettingsService>,
    system: Arc<dyn SystemService>,
    credentials: Arc<CredentialsService>,
-    plugin_accounts: Arc<dyn PluginAccountAccess>,
+    // Runtime 只持有 Weak，这个强引用保障账号端口与 Admin 服务同寿命
+    _plugin_accounts: Arc<dyn PluginAccountAccess>,
    backups: Arc<dyn BackupService>,
    import_tasks: Arc<dyn ImportTasksService>,
 }

 impl AdminServices {
+    #[must_use]
+    pub const fn timezone(&self) -> gateway_core::time::DeploymentTimeZone {
+        self.timezone
+    }
+
+    pub fn public_services(&self) -> Arc<public_service::Registry> {
+        self.public_services.clone()
+    }
+
    #[must_use]
    pub fn plugin_management(&self) -> &PluginManagementService {
        &self.plugin_management
@@ -225,12 +255,6 @@ impl AdminServices {
        self.key_usage.as_ref()
    }

-    /// 取得账号服务的共享句柄；后台编排（冻结恢复 worker）需要持有 Arc。
-    #[must_use]
-    pub fn accounts_handle(&self) -> Arc<dyn AccountsService> {
-        Arc::clone(&self.accounts)
-    }
-
    #[must_use]
    pub fn proxies(&self) -> &dyn ProxiesService {
        self.proxies.as_ref()
@@ -266,7 +290,6 @@ impl AdminServices {
        self.observability.as_ref()
    }

-    #[must_use]
    pub fn settings(&self) -> &dyn SettingsService {
        self.settings.as_ref()
    }
@@ -281,19 +304,13 @@ impl AdminServices {
        self.credentials.as_ref()
    }

-    /// Runtime 只持有该窄端口的 Weak；AdminBundle 保持实际生命周期。
-    #[must_use]
-    pub fn plugin_accounts_handle(&self) -> Arc<dyn PluginAccountAccess> {
-        Arc::clone(&self.plugin_accounts)
-    }
-
    #[must_use]
    pub fn backups(&self) -> &dyn BackupService {
        self.backups.as_ref()
    }
 }

-/// Admin 初始化完成后的封闭能力包。
+/// Admin 初始化完成后的封闭能力包
 pub struct AdminBundle {
    services: AdminServices,
    worker_contributions: Vec<WorkerContribution>,
@@ -305,14 +322,16 @@ impl AdminBundle {
        self.services.clone()
    }

-    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host。
+    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host
    pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
        std::mem::take(&mut self.worker_contributions)
    }
 }

-/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入。
+/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入
 pub struct AdminRuntimePorts {
+    pub timezone: gateway_core::time::DeploymentTimeZone,
+    pub service_middleware: public_service::PlanSource,
    pub plugin_preparation: Arc<dyn ports::plugins::PluginPreparation>,
    pub plugin_management: Arc<dyn ports::plugin_management::PluginManagement>,
    pub published_snapshot: gateway_core::runtime::RuntimeSnapshotHandle,
@@ -328,11 +347,11 @@ pub struct AdminRuntimePorts {
    pub client_key_verifier: Arc<dyn ClientKeyVerifier>,
 }

-/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化。
+/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化
 ///
 /// # Errors
 ///
-/// 配置非法或默认管理员初始化失败时返回错误。
+/// 配置非法或默认管理员初始化失败时返回错误
 pub async fn initialize(
    config: AdminConfig,
    client_config: ClientConfig,
@@ -342,7 +361,7 @@ pub async fn initialize(
    initialize_inner(config, client_config, store, runtime, None).await
 }

-/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例。
+/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例
 pub async fn initialize_with_plugin_accounts(
    config: AdminConfig,
    client_config: ClientConfig,
@@ -361,6 +380,8 @@ async fn initialize_inner(
    plugin_accounts: Option<Arc<dyn PluginAccountAccess>>,
 ) -> Result<AdminBundle, AdminError> {
    let AdminRuntimePorts {
+        timezone,
+        service_middleware,
        plugin_preparation,
        plugin_management,
        published_snapshot,
@@ -384,8 +405,7 @@ async fn initialize_inner(
    let registry = providers;

    let auth = Arc::new(DefaultAuthService::new(
-        config.default_username,
-        config.session_ttl_minutes,
+        &config,
        client_config.session_ttl_minutes,
        store.auth(),
        client_key_verifier.clone(),
@@ -406,23 +426,29 @@ async fn initialize_inner(
        backup_ports.object_store(),
        store.auth(),
        snapshot.clone(),
+        timezone,
    ));
    let backup_task = backup::task::BackupTask::new(
        backup_ports.repository(),
        backup_ports.dump(),
        backup_ports.object_store(),
-    );
+    )
+    .with_timezone(timezone);
    let system_preflight = Arc::new(use_case::plugin_update::PluginSystemUpdatePreflight::new(
        store.plugins(),
        plugin_inspector.clone(),
    ));
    let system = Arc::new(DefaultSystemService::new(system, system_preflight));
+    let observations: Arc<dyn ports::store::ObservabilityStore> = Arc::new(
+        use_case::observability::CachedObservabilityStore::new(store.observability()),
+    );
    let key_usage = Arc::new(use_case::key_usage::DefaultKeyUsageService::new(
        auth.clone(),
        client_key_verifier,
        store.client_keys(),
-        store.observability(),
+        observations.clone(),
        system.clone(),
+        timezone,
    ));
    let credentials = Arc::new(CredentialsService::new(
        registry.clone(),
@@ -435,7 +461,17 @@ async fn initialize_inner(
    });
    let import_tasks = use_case::import_tasks::DefaultImportTasksService::new(credentials.clone());
    let import_task = use_case::import_tasks::ImportTaskWorker(import_tasks.clone());
+    let settings = initialize_settings(
+        store.settings(),
+        snapshot.clone(),
+        registry.clone(),
+        pricing_source,
+    );
+    let mut public_services = public_service::Registry::new(service_middleware);
+    public_services.register_settings(&settings)?;
    let services = AdminServices {
+        timezone,
+        public_services: Arc::new(public_services),
        plugin_management: Arc::new(PluginManagementService::new(
            plugin_management,
            store.plugins(),
@@ -471,20 +507,16 @@ async fn initialize_inner(
        )),
        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
        observability: Arc::new(DefaultObservabilityService::new(
-            store.observability(),
+            observations.clone(),
            store.accounts(),
            store.settings(),
            registry.clone(),
+            timezone,
        )),
-        settings: Arc::new(DefaultSettingsService::new(
-            store.settings(),
-            snapshot.clone(),
-            registry,
-            pricing_source,
-        )),
+        settings,
        system,
        credentials,
-        plugin_accounts,
+        _plugin_accounts: plugin_accounts,
        import_tasks,
        backups,
    };
@@ -516,7 +548,7 @@ async fn initialize_inner(
    })
 }

-/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计。
+/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计
 pub fn initialize_plugin_accounts(
    providers: ports::provider::ProviderAdminRegistry,
    accounts: Arc<dyn ports::store::AccountStore>,
@@ -527,7 +559,7 @@ pub fn initialize_plugin_accounts(
    ))
 }

-/// 为 Runtime 创建只暴露非秘密 Client Key 目录的窄端口。
+/// 为 Runtime 创建非秘密 Client Key 目录与预算重置的窄端口
 #[must_use]
 pub fn initialize_plugin_client_keys(
    providers: ports::provider::ProviderAdminRegistry,
@@ -539,7 +571,16 @@ pub fn initialize_plugin_client_keys(
    Arc::new(use_case::plugin_client_keys::DefaultPluginClientKeyAccess::new(service))
 }

-/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
+/// 为 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> {
@@ -558,7 +599,7 @@ fn backup_worker_contribution(
    Ok(vec![WorkerContribution::Registration(registration)])
 }

-/// 冻结恢复 Worker 注册：按固定周期扫描活跃冻结，owner 固定。
+/// 冻结恢复 Worker 注册：按固定周期扫描活跃冻结，owner 固定
 fn freeze_recovery_worker_contribution(
    task: freeze_recovery::FreezeRecoveryTask,
 ) -> Result<Vec<WorkerContribution>, AdminError> {
@@ -588,3 +629,18 @@ fn freeze_recovery_worker_contribution(
    .map_err(|_| AdminError::internal("冻结恢复 Worker 注册信息不合法"))?;
    Ok(vec![WorkerContribution::Registration(registration)])
 }
+
+/// 设置服务不依赖 Web 管理会话，CLI 与服务器通过同一用例执行事务和发布
+pub fn initialize_settings(
+    store: Arc<dyn ports::store::SettingsStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+    providers: ProviderAdminRegistry,
+    pricing_source: Arc<dyn ports::pricing::PricingSource>,
+) -> Arc<dyn SettingsService> {
+    Arc::new(DefaultSettingsService::new(
+        store,
+        snapshot,
+        providers,
+        pricing_source,
+    ))
+}
@@ -1,13 +1,33 @@
-//! Provider-neutral account group commands and projections.
+//! 跨 Provider 账号分组的管理命令与查询投影

 use std::collections::BTreeMap;

 use chrono::{DateTime, Utc};
-use gateway_core::{account::AccountStatusFacts, routing::AccountGroupId};
+use gateway_core::{
+    account::{AccountStatusFacts, FastMode},
+    routing::AccountGroupId,
+};

 use super::{PageSize, Revision, observability::DecimalAmount};

-/// Canonical `#RRGGBBAA` color persisted with an account group.
+/// 名称与描述的共同约束，HTTP、用例和存储边界只映射错误
+pub fn validate_group_fields(
+    name: &str,
+    description: Option<&str>,
+) -> Result<(), super::AdminModelError> {
+    if name.trim() != name
+        || name.is_empty()
+        || name.chars().count() > 100
+        || name.chars().any(char::is_control)
+        || description
+            .is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
+    {
+        return Err(super::AdminModelError::InvalidAccountGroupFields);
+    }
+    Ok(())
+}
+
+/// 账号分组持久化使用的标准 `#RRGGBBAA` 颜色
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupColor(String);

@@ -26,7 +46,7 @@ impl AccountGroupColor {
    }
 }

-/// Group member availability at the current observation time.
+/// 当前观测时刻的分组成员可用性
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountGroupAccountSummary {
    pub available: u64,
@@ -34,23 +54,23 @@ pub struct AccountGroupAccountSummary {
    pub total: u64,
 }

-/// Group scheduling slots derived from available accounts and runtime leases.
+/// 根据可用账号与运行时租约计算的分组调度槽位
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountGroupCapacity {
    pub used_slots: Option<u64>,
-    /// `None` 表示可用账号中存在不限制并发的账号。
+    /// `None` 表示可用账号中存在不限制并发的账号
    pub total_slots: Option<u64>,
 }

-/// Successful, downstream-committed USD request costs for group accounts.
+/// 分组账号成功且已向下游交付的请求美元费用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupUsage {
    pub today_usd: DecimalAmount,
-    /// 当前 usage retention 窗口内、按请求发生时 routing group 快照归属的累计成本。
+    /// 当前 usage retention 窗口内、当前组成员实际完成请求的累计成本
    pub retained_total_usd: DecimalAmount,
 }

-/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并。
+/// 当前页账号组 membership 对应的持久账号事实；运行态在 Admin query service 合并
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupMemberFact {
    pub group_id: AccountGroupId,
@@ -59,7 +79,7 @@ pub struct AccountGroupMemberFact {
    pub total_slots: Option<u64>,
 }

-/// Lightweight group reference embedded in account and client-key views.
+/// 账号与 Client Key 视图内嵌的轻量分组引用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupRef {
    pub id: AccountGroupId,
@@ -68,7 +88,7 @@ pub struct AccountGroupRef {
    pub enabled: bool,
 }

-/// Account group list query.
+/// 账号分组列表查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupListQuery {
    pub page: u32,
@@ -77,10 +97,10 @@ pub struct AccountGroupListQuery {
    pub enabled: Option<bool>,
 }

-/// Complete account group summary.
+/// 完整账号分组摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupRecord {
-    pub disable_fast: bool,
+    pub fast_mode: FastMode,
    pub id: AccountGroupId,
    pub name: String,
    pub description: Option<String>,
@@ -96,7 +116,7 @@ pub struct AccountGroupRecord {
    pub updated_at: DateTime<Utc>,
 }

-/// Paginated account groups.
+/// 账号分组分页结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupPage {
    pub config_revision: Revision,
@@ -106,49 +126,59 @@ pub struct AccountGroupPage {
    pub page_size: u16,
 }

-/// Create an account group.
+/// 分组选择器使用的轻量分页结果
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountGroupOptionsPage {
+    pub config_revision: Revision,
+    pub items: Vec<AccountGroupRef>,
+    pub total: u64,
+    pub page: u32,
+    pub page_size: u16,
+}
+
+/// 创建账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateAccountGroup {
-    pub disable_fast: bool,
+    pub fast_mode: FastMode,
    pub name: String,
    pub description: Option<String>,
    pub color: AccountGroupColor,
 }

-/// Store-ready create command with a generated stable ID.
+/// 已生成稳定标识、可直接提交存储的创建命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct NewAccountGroup {
-    pub disable_fast: bool,
+    pub fast_mode: FastMode,
    pub id: AccountGroupId,
    pub name: String,
    pub description: Option<String>,
    pub color: AccountGroupColor,
 }

-/// Update an account group's descriptive fields.
+/// 更新账号分组的描述字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateAccountGroup {
-    pub disable_fast: Option<bool>,
+    pub fast_mode: Option<FastMode>,
    pub id: AccountGroupId,
    pub name: String,
    pub description: Option<String>,
    pub color: AccountGroupColor,
 }

-/// Enable or disable an account group.
+/// 启用或停用账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SetAccountGroupEnabled {
    pub id: AccountGroupId,
    pub enabled: bool,
 }

-/// Delete an account group that is not referenced by a client key.
+/// 删除未被 Client Key 引用的账号分组
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteAccountGroup {
    pub id: AccountGroupId,
 }

-/// Result of any account-group mutation.
+/// 账号分组变更结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountGroupMutation {
    pub config_revision: Revision,
@@ -1,4 +1,4 @@
-//! 多 Provider 账号目录与连接测试的公共事实。
+//! 多 Provider 账号目录与连接测试的公共事实

 use std::{collections::BTreeMap, pin::Pin};

@@ -18,7 +18,7 @@ pub use gateway_core::account::{
    QuotaState, resolve_account_status,
 };

-/// 账号可用的管理操作。
+/// 账号可用的管理操作
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct ProviderAccountCapabilities {
    pub quota: bool,
@@ -30,7 +30,7 @@ pub struct ProviderAccountCapabilities {
    pub consume_reset_credit: bool,
 }

-/// 导入时统一应用的账号备注、调度与分组设置；缺省时保留原有导入语义。
+/// 导入时统一应用的账号备注、调度与分组设置；缺省时保留原有导入语义
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountImportSettings {
    pub notes: Option<String>,
@@ -41,7 +41,7 @@ pub struct AccountImportSettings {
    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
 }

-/// 账号列表排序字段。
+/// 账号列表排序字段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AccountSortField {
    Email,
@@ -52,21 +52,21 @@ pub enum AccountSortField {
    ExpiresAt,
 }

-/// 账号列表排序方向。
+/// 账号列表排序方向
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SortDirection {
    Asc,
    Desc,
 }

-/// 一组完整的账号排序规则。
+/// 一组完整的账号排序规则
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct AccountSort {
    pub field: AccountSortField,
    pub direction: SortDirection,
 }

-/// 账号列表的存储查询条件。
+/// 账号列表的存储查询条件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountListQuery {
    pub page: u32,
@@ -78,15 +78,15 @@ pub struct AccountListQuery {
    pub sort: Option<AccountSort>,
 }

-/// Admin query service 从运行态存储取得的当前账号冷却快照。
+/// Admin query service 从运行态存储取得的当前账号冷却快照
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct AccountRuntimeSnapshot {
    pub cooldown: BTreeMap<String, gateway_core::account::AccountCooldown>,
-    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零
    pub in_flight: Option<BTreeMap<String, u64>>,
 }

-/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结。
+/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountFreeze {
    pub credential_revision: Revision,
@@ -95,14 +95,14 @@ pub struct AccountFreeze {
    pub requires_probe: bool,
 }

-/// Optional account membership filter.
+/// 可选的账号分组成员筛选条件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountGroupFilter {
    Group(gateway_core::routing::AccountGroupId),
    Ungrouped,
 }

-/// 账号公共存储投影；Provider 专属字段不进入此结构。
+/// 账号公共存储投影；Provider 专属字段不进入此结构
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountRecord {
    pub id: String,
@@ -133,42 +133,12 @@ pub struct AccountRecord {
    pub updated_at: DateTime<Utc>,
 }

-/// 单一货币的账号成本聚合。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountCost {
-    pub currency: String,
-    pub amount: super::observability::DecimalAmount,
-}
+pub use super::observability::{
+    AccountModelUsage, AccountPoolMetrics as AccountSummary, AccountRequestBucket,
+    CurrencyCost as AccountCost,
+};

-/// 账号在一个模型上的历史用量。
-#[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,
@@ -176,9 +146,9 @@ pub struct AccountUsage {
    pub success_count: u64,
    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
-    pub cached_tokens: Option<u64>,
-    pub cache_write_tokens: Option<u64>,
-    pub reasoning_tokens: Option<u64>,
+    pub cached_input_tokens: Option<u64>,
+    pub cache_write_input_tokens: Option<u64>,
+    pub reasoning_output_tokens: Option<u64>,
    pub image_input_tokens: Option<u64>,
    pub image_output_tokens: Option<u64>,
    pub image_request_count: u64,
@@ -191,9 +161,9 @@ pub struct AccountUsage {
    pub models: Vec<AccountModelUsage>,
 }

-/// 某个账号在调用方指定时间窗口内的本地用量查询。
+/// 某个账号在调用方指定时间窗口内的本地用量查询
 ///
-/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义。
+/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowQuery {
    pub account_id: String,
@@ -201,7 +171,7 @@ pub struct AccountUsageWindowQuery {
    pub range: TimeRange,
 }

-/// 一个账号时间窗口用量查询的结果。
+/// 一个账号时间窗口用量查询的结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowResult {
    pub account_id: String,
@@ -209,7 +179,7 @@ pub struct AccountUsageWindowResult {
    pub usage: AccountUsage,
 }

-/// 账号列表页所需的完整存储事实。
+/// 账号列表页所需的完整存储事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPage {
    pub config_revision: Revision,
@@ -218,31 +188,28 @@ pub struct AccountPage {
    pub summary: AccountSummary,
 }

-/// 同一状态快照下的账号事实与唯一状态投影。
+/// 同一状态快照下的账号事实与唯一状态投影
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPageItem {
    pub account: AccountRecord,
    pub projection: AccountStatusProjection,
+    pub capacity: AccountCapacity,
 }

-/// 统一账号目录的全局状态计数，不受当前筛选和分页影响。
-///
-/// 计数与 [`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,
+pub struct AccountCapacity {
+    /// 实时租约读取失败时为 `None`，不能当作空闲
+    pub used_slots: Option<u64>,
+    /// 应用账号覆盖或全局默认值后的上限；`None` 表示不限
+    pub total_slots: Option<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>,
@@ -252,14 +219,14 @@ pub struct UpdateAccount {
    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }

-/// 账号更新结果。
+/// 账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUpdateResult {
    pub config_revision: Revision,
    pub account_id: gateway_core::account::ProviderAccountId,
 }

-/// 仅修改显式字段的批量账号设置命令。
+/// 仅修改显式字段的批量账号设置命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BatchUpdateAccounts {
    pub account_ids: Vec<String>,
@@ -271,20 +238,20 @@ pub struct BatchUpdateAccounts {
    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }

-/// 批量账号更新结果。
+/// 批量账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountsUpdateResult {
    pub config_revision: Revision,
    pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
 }

-/// 账号批量删除命令。
+/// 账号批量删除命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteAccounts {
    pub account_ids: Vec<String>,
 }

-/// 账号连接测试的语义事件。
+/// 账号连接测试的语义事件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountConnectionTestEvent {
    Started {
@@ -313,6 +280,6 @@ pub enum AccountConnectionTestEvent {
    },
 }

-/// 每次连接测试独占的有限事件流。
+/// 每次连接测试独占的有限事件流
 pub type AccountConnectionTestEventStream =
    Pin<Box<dyn Stream<Item = AccountConnectionTestEvent> + Send + 'static>>;
@@ -0,0 +1,65 @@
+//! 统计投影的新鲜度、覆盖范围与预计算费用合同
+
+use chrono::{DateTime, Utc};
+
+use super::observability::{DecimalAmount, RequestMetricPoint, UsageOverview};
+
+/// 数据可见性状态，不以缺失投影冒充零统计
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
+pub enum AnalyticsState {
+    Ready,
+    #[default]
+    Building,
+    Lagging,
+    Stale,
+}
+
+impl AnalyticsState {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Ready => "ready",
+            Self::Building => "building",
+            Self::Lagging => "lagging",
+            Self::Stale => "stale",
+        }
+    }
+}
+
+/// 与统计结果在同一读取快照内取得的覆盖和版本事实
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct AnalyticsMetadata {
+    pub coverage_start: Option<DateTime<Utc>>,
+    pub coverage_end: Option<DateTime<Utc>>,
+    pub generated_at: DateTime<Utc>,
+    pub lag_seconds: u64,
+    pub state: AnalyticsState,
+    pub percentiles_approximate: bool,
+    pub schema_version: u32,
+    pub histogram_version: u32,
+    /// 派生数据版本供缓存判断失效，不作为源事务提交顺序
+    pub generation: u64,
+}
+
+/// 单次请求经 Provider 费用合同确认后可累加的 USD 情景金额
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct UsageBillingProjection {
+    pub standard_amount: Option<DecimalAmount>,
+    pub no_cache_amount: Option<DecimalAmount>,
+}
+
+/// 时间桶内的情景费用，未知金额不改写为零
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageProjectedCostPoint {
+    pub bucket_start: DateTime<Utc>,
+    pub standard_amount: Option<DecimalAmount>,
+    pub no_cache_amount: Option<DecimalAmount>,
+}
+
+/// 同一数据库快照内的完整洞察输入
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UsageInsightsObservation {
+    pub overview: UsageOverview,
+    pub trend: Vec<RequestMetricPoint>,
+    pub costs: Vec<UsageProjectedCostPoint>,
+}
@@ -0,0 +1,153 @@
+//! 管理写入的审计分类；适配器只能补充事务实际写入的字段与实体标识
+
+use super::{
+    MutationActor, MutationContext,
+    auth::{AdminAuditEvent, AuditActorKind, admin_session_actor_ref},
+};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum MutationAuditOperation {
+    ModelPricingSync,
+    ModelPricingUpdate,
+    RuntimeSettingsReplace,
+    AdminApiKeyChanged { exists: bool },
+    AccountGroupCreate,
+    AccountGroupUpdate,
+    AccountGroupEnabled { enabled: bool },
+    AccountGroupDelete,
+    ClientApiKeyResetBudget,
+    ProviderAccountUpdate,
+    BackupStorageUpdate,
+    BackupScheduleUpdate,
+    ProviderAccountAdaptConcurrency,
+    ProviderAccountRecover,
+    ProviderAccountBatchUpdate,
+    ProviderAccountDelete,
+    ProviderAccountExportCredentials,
+    PluginArtifactInstall,
+    PluginArtifactAccept,
+    PluginArtifactDelete,
+    PluginInstanceConfigure,
+    PluginInstanceDelete,
+    PluginSourceCredentialCreate,
+    PluginSourceCredentialDelete,
+    ClientApiKeyUpdateBudgetLimits,
+    ClientApiKeyCreate,
+    ClientApiKeyUpdate,
+    ClientApiKeyEnabled { enabled: bool },
+    ClientApiKeyDelete,
+    PluginSourceChangeSource,
+    PluginSourceDelete,
+    OutboundProxyCreate,
+    OutboundProxyUpdate,
+    OutboundProxyDelete,
+    OutboundProxyTest,
+    AccountGroupPluginReconcile,
+    ClientApiKeyPluginReconcile,
+    ProviderAccountImportDocument,
+    ProviderAccountRotateCredential,
+    ProviderAccountRefreshCredential,
+    ProviderAccountAuthorize,
+    ProviderAccountReauthorize,
+}
+
+impl MutationAuditOperation {
+    #[must_use]
+    pub const fn classification(self) -> (&'static str, &'static str) {
+        match self {
+            Self::ModelPricingSync => ("pricing.sync", "model_pricing"),
+            Self::ModelPricingUpdate => ("pricing.update", "model_pricing"),
+            Self::RuntimeSettingsReplace => ("settings.replace", "runtime_settings"),
+            Self::AdminApiKeyChanged { exists } => (
+                if exists {
+                    "admin_api_key.replace"
+                } else {
+                    "admin_api_key.delete"
+                },
+                "runtime_settings",
+            ),
+            Self::AccountGroupCreate => ("create", "account_group"),
+            Self::AccountGroupUpdate => ("update", "account_group"),
+            Self::AccountGroupEnabled { enabled } => {
+                (if enabled { "enable" } else { "disable" }, "account_group")
+            }
+            Self::AccountGroupDelete => ("delete", "account_group"),
+            Self::ClientApiKeyResetBudget => ("reset_budget", "client_api_key"),
+            Self::ProviderAccountUpdate => ("update", "provider_account"),
+            Self::BackupStorageUpdate => ("backup.s3_config_updated", "backup_settings"),
+            Self::BackupScheduleUpdate => ("backup.schedule_updated", "backup_settings"),
+            Self::ProviderAccountAdaptConcurrency => ("adapt_concurrency", "provider_account"),
+            Self::ProviderAccountRecover => ("recover", "provider_account"),
+            Self::ProviderAccountBatchUpdate => ("batch_update", "provider_account"),
+            Self::ProviderAccountDelete => ("delete", "provider_account"),
+            Self::ProviderAccountExportCredentials => ("export_credentials", "provider_account"),
+            Self::PluginArtifactInstall => ("install", "plugin_artifact"),
+            Self::PluginArtifactAccept => ("accept", "plugin_artifact"),
+            Self::PluginArtifactDelete => ("delete", "plugin_artifact"),
+            Self::PluginInstanceConfigure => ("configure", "plugin_instance"),
+            Self::PluginInstanceDelete => ("delete", "plugin_instance"),
+            Self::PluginSourceCredentialCreate => ("create", "plugin_source_credential"),
+            Self::PluginSourceCredentialDelete => ("delete", "plugin_source_credential"),
+            Self::ClientApiKeyUpdateBudgetLimits => ("update_budget_limits", "client_api_key"),
+            Self::ClientApiKeyCreate => ("create", "client_api_key"),
+            Self::ClientApiKeyUpdate => ("update", "client_api_key"),
+            Self::ClientApiKeyEnabled { enabled } => {
+                (if enabled { "enable" } else { "disable" }, "client_api_key")
+            }
+            Self::ClientApiKeyDelete => ("delete", "client_api_key"),
+            Self::PluginSourceChangeSource => ("change_source", "plugin_source"),
+            Self::PluginSourceDelete => ("delete", "plugin_source"),
+            Self::OutboundProxyCreate => ("create", "outbound_proxy"),
+            Self::OutboundProxyUpdate => ("update", "outbound_proxy"),
+            Self::OutboundProxyDelete => ("delete", "outbound_proxy"),
+            Self::OutboundProxyTest => ("test", "outbound_proxy"),
+            Self::AccountGroupPluginReconcile => ("plugin_reconcile", "account_group"),
+            Self::ClientApiKeyPluginReconcile => ("plugin_reconcile", "client_api_key"),
+            Self::ProviderAccountImportDocument => ("import_document", "provider_account"),
+            Self::ProviderAccountRotateCredential => ("rotate_credential", "provider_account"),
+            Self::ProviderAccountRefreshCredential => ("refresh_credential", "provider_account"),
+            Self::ProviderAccountAuthorize => ("authorize", "provider_account"),
+            Self::ProviderAccountReauthorize => ("reauthorize", "provider_account"),
+        }
+    }
+}
+
+/// 分类与稳定实体标识共同组成审计意图，字段差异由同一提交事务补齐
+#[derive(Debug, Clone, Copy)]
+pub struct MutationAuditIntent<'a> {
+    pub operation: MutationAuditOperation,
+    pub entity_ref: &'a str,
+}
+
+impl MutationAuditIntent<'_> {
+    #[must_use]
+    pub fn event(self, context: &MutationContext, changed_fields: Vec<String>) -> AdminAuditEvent {
+        let (actor_kind, actor_admin_user_id, actor_ref) = match &context.actor {
+            MutationActor::AdminSession { admin_user_id } => (
+                AuditActorKind::AdminSession,
+                Some(admin_user_id.clone()),
+                admin_session_actor_ref(admin_user_id),
+            ),
+            MutationActor::AdminApiKey => (
+                AuditActorKind::AdminApiKey,
+                None,
+                "admin_api_key".to_owned(),
+            ),
+            MutationActor::System => (AuditActorKind::System, None, "system".to_owned()),
+        };
+        let (action, entity_kind) = self.operation.classification();
+        AdminAuditEvent {
+            id: format!("audit_{}", uuid::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: entity_kind.to_owned(),
+            entity_ref: self.entity_ref.to_owned(),
+            config_revision: None,
+            changed_fields,
+            occurred_at: chrono::Utc::now(),
+        }
+    }
+}
@@ -1,24 +1,30 @@
-//! 控制面认证、统一会话和管理员安全审计事实。
+//! 控制面认证、统一会话和管理员安全审计事实

 use chrono::{DateTime, Utc};
 use gateway_core::{engine::execution::ClientAuthenticationError, policy::ClientApiKeyId};

 use super::{MutationActor, MutationContext, Revision};

-/// 会话审计使用的稳定管理员标识。
+/// 会话审计使用的稳定管理员标识
 #[must_use]
 pub fn admin_session_actor_ref(admin_user_id: &str) -> String {
    format!("admin:{admin_user_id}")
 }

-/// 已认证的管理主体。
+/// 已认证的管理主体
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AdminPrincipal {
-    Session { admin_user_id: String },
+    Session {
+        admin_user_id: String,
+    },
    ApiKey,
+    /// 安装者完整信任的插件；身份仅由内部 HTTP 分派端口签发
+    Plugin {
+        instance_id: String,
+    },
 }

-/// 传给管理用例的安全请求上下文。
+/// 传给管理用例的安全请求上下文
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AdminRequestContext {
    pub principal: AdminPrincipal,
@@ -33,6 +39,7 @@ impl AdminRequestContext {
                admin_user_id: admin_user_id.clone(),
            },
            AdminPrincipal::ApiKey => MutationActor::AdminApiKey,
+            AdminPrincipal::Plugin { .. } => MutationActor::System,
        };
        MutationContext {
            actor,
@@ -41,7 +48,7 @@ impl AdminRequestContext {
    }
 }

-/// 登录方式只决定凭据验证流程，不能直接授予会话权限。
+/// 登录方式只决定凭据验证流程，不能直接授予会话权限
 #[derive(Clone, PartialEq, Eq)]
 pub enum LoginCommand {
    Admin {
@@ -69,24 +76,29 @@ impl std::fmt::Debug for LoginCommand {
    }
 }

-/// 登录成功后返回的会话事实。
+/// 登录或刷新后仅向当前浏览器交付的会话凭据
 #[derive(Clone, PartialEq, Eq)]
-pub struct LoginResult {
+pub struct SessionGrant {
    pub session_id: String,
+    pub refresh_token: Option<String>,
    pub session: AuthSession,
 }

-impl std::fmt::Debug for LoginResult {
+impl std::fmt::Debug for SessionGrant {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        formatter
-            .debug_struct("LoginResult")
+            .debug_struct("SessionGrant")
            .field("session_id", &"[REDACTED]")
+            .field(
+                "refresh_token",
+                &self.refresh_token.as_ref().map(|_| "[REDACTED]"),
+            )
            .field("session", &self.session)
            .finish()
    }
 }

-/// 登录状态机可被 API 精确映射的失败类型。
+/// 登录状态机可被 API 精确映射的失败类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum LoginError {
    #[error("invalid login credentials")]
@@ -107,7 +119,7 @@ impl From<ClientAuthenticationError> for LoginError {
    }
 }

-/// 服务端已验证的身份绑定，不保存密码或原始 API Key。
+/// 服务端已验证的身份绑定，不保存密码或原始 API Key
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SessionSubject {
    Admin {
@@ -119,7 +131,7 @@ pub enum SessionSubject {
    },
 }

-/// 仅已登录管理员可以修改自己的密码。
+/// 仅已登录管理员可以修改自己的密码
 pub struct ChangePassword {
    pub current_password: String,
    pub new_password: String,
@@ -131,14 +143,44 @@ impl std::fmt::Debug for ChangePassword {
    }
 }

-/// 两种登录方式共用的固定有效期会话。
+/// 访问有效期与逻辑会话；没有续期凭据的会话保持固定期限
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthSession {
    pub subject: SessionSubject,
    pub expires_at: DateTime<Utc>,
+    pub absolute_expires_at: Option<DateTime<Utc>>,
+    pub renewal: Option<SessionRenewal>,
 }

-/// 安全审计事件类型。
+/// 长效登录的凭据摘要与续期窗口；访问到期不删除整段登录
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionRenewal {
+    pub expires_at: DateTime<Utc>,
+    pub access_digest: [u8; 32],
+    pub refresh_digest: [u8; 32],
+    pub previous: Option<SessionRefreshReplay>,
+}
+
+/// 仅保存上一代摘要及派生盐；响应丢失时须持有上一代凭据才能重建同一响应
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct SessionRefreshReplay {
+    pub digest: [u8; 32],
+    pub salt: [u8; 32],
+    pub expires_at: DateTime<Utc>,
+}
+
+impl AuthSession {
+    #[must_use]
+    pub fn retained_until(&self) -> DateTime<Utc> {
+        self.renewal
+            .as_ref()
+            .map_or(self.expires_at, |renewal| renewal.expires_at)
+    }
+}
+
+/// 安全审计事件类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AuditActorKind {
    AdminSession,
@@ -147,7 +189,7 @@ pub enum AuditActorKind {
    Anonymous,
 }

-/// 管理写操作留下的最小审计事实。
+/// 管理写操作留下的最小审计事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AdminAuditEvent {
    pub id: String,
@@ -1,34 +1,33 @@
-//! 备份领域的稳定错误码。
+//! 备份领域的稳定错误码

-/// 配置或参数非法。
+/// 配置或参数非法
 pub const INVALID_CONFIG: &str = "backup.invalid_config";
-/// Cron 表达式非法。
+/// Cron 表达式非法
 pub const INVALID_CRON: &str = "backup.invalid_cron";
-/// IANA 时区非法。
-pub const INVALID_TIMEZONE: &str = "backup.invalid_timezone";
-/// 记录不存在。
+/// IANA 时区非法
+/// 记录不存在
 pub const RECORD_NOT_FOUND: &str = "backup.record_not_found";
-/// 已存在活跃任务，拒绝创建。
+/// 已存在活跃任务，拒绝创建
 pub const ACTIVE_TASK_CONFLICT: &str = "backup.active_task_conflict";
-/// 记录状态与期望不符，无法迁移。
+/// 记录状态与期望不符，无法迁移
 pub const STATE_CONFLICT: &str = "backup.state_conflict";
-/// 已有记录时禁止切换存储目标。
+/// 已有记录时禁止切换存储目标
 pub const STORAGE_IDENTITY_LOCKED: &str = "backup.storage_identity_locked";
-/// `pg_dump` 非零退出或失败。
+/// `pg_dump` 非零退出或失败
 pub const PG_DUMP_FAILED: &str = "backup.pg_dump_failed";
-/// 暂存磁盘空间不足。
+/// 暂存磁盘空间不足
 pub const STAGING_SPACE_EXHAUSTED: &str = "backup.staging_space_exhausted";
-/// S3 认证失败。
+/// S3 认证失败
 pub const S3_AUTH_FAILED: &str = "backup.s3_auth_failed";
-/// S3 权限拒绝。
+/// S3 权限拒绝
 pub const S3_PERMISSION_DENIED: &str = "backup.s3_permission_denied";
-/// S3 上传失败。
+/// S3 上传失败
 pub const S3_UPLOAD_FAILED: &str = "backup.s3_upload_failed";
-/// 远端对象校验失败。
+/// 远端对象校验失败
 pub const REMOTE_VERIFICATION_FAILED: &str = "backup.remote_verification_failed";
-/// 任务被取消。
+/// 任务被取消
 pub const CANCELLED: &str = "backup.cancelled";
-/// 仓储或对象存储暂不可用。
+/// 仓储或对象存储暂不可用
 pub const STORE_UNAVAILABLE: &str = "backup.store_unavailable";
-/// 上游 S3 服务返回无效或失败响应。
+/// 上游 S3 服务返回无效或失败响应
 pub const UPSTREAM_FAILURE: &str = "backup.upstream_failure";
@@ -1,8 +1,10 @@
-//! S3 备份领域模型、状态机与稳定错误。
+//! S3 备份领域模型、状态机与稳定错误
 //!
-//! 领域类型只携带事实，不承载基础设施细节。Secret 使用 [`secrecy::SecretString`]，
-//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志。管理员身份等审计事实
-//! 只存在于 `admin_audit_events`，本模型不重复保存。
+//! 领域类型只携带事实，不承载基础设施细节
+//! Secret 使用 [`secrecy::SecretString`]，
+//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志
+//! 管理员身份等审计事实
+//! 只存在于 `admin_audit_events`，本模型不重复保存

 use std::fmt;

@@ -12,7 +14,7 @@ use uuid::Uuid;

 use super::PageSize;

-/// 备份触发来源。
+/// 备份触发来源
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BackupTriggerKind {
    Manual,
@@ -20,7 +22,7 @@ pub enum BackupTriggerKind {
 }

 impl BackupTriggerKind {
-    /// 稳定持久化值。
+    /// 稳定持久化值
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
@@ -29,7 +31,7 @@ impl BackupTriggerKind {
        }
    }

-    /// 解析持久化值。
+    /// 解析持久化值
    #[must_use]
    pub fn parse(value: &str) -> Option<Self> {
        match value {
@@ -46,11 +48,11 @@ impl fmt::Display for BackupTriggerKind {
    }
 }

-/// 备份任务状态机（六状态）。
+/// 备份任务状态机（六状态）
 ///
 /// 迁移 `backup_records_lifecycle_ck` 与字段空值语义共同定义合法持久化行；
-/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足。
-/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态。
+/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足
+/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum BackupStatus {
    Queued,
@@ -62,7 +64,7 @@ pub enum BackupStatus {
 }

 impl BackupStatus {
-    /// 稳定持久化值。
+    /// 稳定持久化值
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
@@ -75,7 +77,7 @@ impl BackupStatus {
        }
    }

-    /// 解析持久化值。
+    /// 解析持久化值
    #[must_use]
    pub fn parse(value: &str) -> Option<Self> {
        match value {
@@ -89,19 +91,19 @@ impl BackupStatus {
        }
    }

-    /// 该状态是否消耗全局活跃名额。
+    /// 该状态是否消耗全局活跃名额
    #[must_use]
    pub const fn is_active(self) -> bool {
        matches!(self, Self::Queued | Self::Dumping | Self::Uploading)
    }

-    /// 该状态是否允许进入删除流程。
+    /// 该状态是否允许进入删除流程
    #[must_use]
    pub const fn can_be_deleted(self) -> bool {
        matches!(self, Self::Completed | Self::Failed)
    }

-    /// 领域内允许的显式迁移。
+    /// 领域内允许的显式迁移
    #[must_use]
    pub fn allows_transition_to(self, target: BackupStatus) -> bool {
        matches!(
@@ -124,7 +126,34 @@ impl fmt::Display for BackupStatus {
    }
 }

-/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值。
+/// 已通过领域状态机校验的显式迁移
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct BackupStatusTransition {
+    from: BackupStatus,
+    to: BackupStatus,
+}
+
+impl BackupStatusTransition {
+    /// 校验并构造显式迁移；非法状态边返回 `None`
+    #[must_use]
+    pub fn try_new(from: BackupStatus, to: BackupStatus) -> Option<Self> {
+        from.allows_transition_to(to).then_some(Self { from, to })
+    }
+
+    /// 迁移要求的当前状态
+    #[must_use]
+    pub const fn from(self) -> BackupStatus {
+        self.from
+    }
+
+    /// 迁移完成后的目标状态
+    #[must_use]
+    pub const fn to(self) -> BackupStatus {
+        self.to
+    }
+}
+
+/// S3 存储配置更新命令；`secret_access_key` 为 `None` 表示保留旧值
 #[derive(Clone)]
 pub struct UpdateBackupStorageCommand {
    pub endpoint: String,
@@ -151,19 +180,18 @@ impl fmt::Debug for UpdateBackupStorageCommand {
    }
 }

-/// 调度配置更新命令。
+/// 调度配置更新命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateBackupScheduleCommand {
    pub schedule_enabled: bool,
    pub cron_expression: String,
-    pub schedule_timezone: String,
    pub retention_days: u32,
    pub retention_count: u32,
 }

-/// 完整保存的备份设置（含 Secret）。
+/// 完整保存的备份设置（含 Secret）
 ///
-/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志。
+/// 只从仓储读取；不实现 `Serialize`，防止 Secret 进入 wire 或日志
 #[derive(Clone)]
 pub struct BackupSettings {
    pub storage_revision: u64,
@@ -176,6 +204,7 @@ pub struct BackupSettings {
    pub force_path_style: bool,
    pub schedule_enabled: bool,
    pub cron_expression: Option<String>,
+    /// 记录持久化游标采用的时区，由服务端维护，不是独立部署设置
    pub schedule_timezone: Option<String>,
    pub retention_days: u32,
    pub retention_count: u32,
@@ -209,7 +238,7 @@ impl fmt::Debug for BackupSettings {
 }

 impl BackupSettings {
-    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）。
+    /// S3 存储配置是否完整（bucket/region/密钥/前缀齐全）
    #[must_use]
    pub fn storage_configured(&self) -> bool {
        self.endpoint.is_some()
@@ -220,14 +249,14 @@ impl BackupSettings {
            && self.prefix.is_some()
    }

-    /// 探测是否已对当前 revision 成功；`last_verified_at` 非空即表示当前配置已通过探针。
+    /// 探测是否已对当前 revision 成功；`last_verified_at` 非空即表示当前配置已通过探针
    #[must_use]
    pub fn storage_verified(&self) -> bool {
        self.last_verified_at.is_some()
    }
 }

-/// 已经校验并可用于对象存储操作的存储配置快照。
+/// 已经校验并可用于对象存储操作的存储配置快照
 #[derive(Clone)]
 pub struct BackupStorageConfig {
    pub storage_revision: u64,
@@ -257,7 +286,7 @@ impl fmt::Debug for BackupStorageConfig {
 }

 impl BackupStorageConfig {
-    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`。
+    /// 从完整设置推导对象存储配置；设置不完整时返回 `None`
    #[must_use]
    pub fn from_settings(settings: &BackupSettings) -> Option<Self> {
        Some(Self {
@@ -273,7 +302,7 @@ impl BackupStorageConfig {
    }
 }

-/// 一条备份记录。
+/// 一条备份记录
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecord {
    pub id: String,
@@ -288,13 +317,13 @@ pub struct BackupRecord {
    pub error_message: Option<String>,
    pub started_at: Option<DateTime<Utc>>,
    pub completed_at: Option<DateTime<Utc>>,
-    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理。
+    /// 创建时确定的过期时间；手工和计划备份均可设置，到期自动清理
    pub expires_at: Option<DateTime<Utc>>,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
 }

-/// 备份记录分页查询。
+/// 备份记录分页查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordListQuery {
    pub page: u32,
@@ -303,7 +332,7 @@ pub struct BackupRecordListQuery {
    pub trigger: Option<BackupTriggerKind>,
 }

-/// 备份记录分页结果。
+/// 备份记录分页结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordPage {
    pub items: Vec<BackupRecord>,
@@ -313,7 +342,7 @@ pub struct BackupRecordPage {
 }

 impl BackupRecordPage {
-    /// 计算总页数；空集合视为一页。
+    /// 计算总页数；空集合视为一页
    #[must_use]
    pub fn total_pages(&self) -> u32 {
        let size = u64::from(self.page_size.get());
@@ -325,7 +354,7 @@ impl BackupRecordPage {
    }
 }

-/// 创建备份任务的持久化数据；id 与对象 key 由领域生成。
+/// 创建备份任务的持久化数据；id 与对象 key 由领域生成
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupRecordSeed {
    pub id: String,
@@ -335,7 +364,7 @@ pub struct BackupRecordSeed {
    pub expires_at: Option<DateTime<Utc>>,
 }

-/// 连接测试结果；只携带稳定阶段与脱敏消息。
+/// 连接测试结果；只携带稳定阶段与脱敏消息
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConnectionTestResult {
    pub ok: bool,
@@ -344,7 +373,7 @@ pub struct ConnectionTestResult {
    pub message: String,
 }

-/// 对象存储探测阶段。
+/// 对象存储探测阶段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ConnectionTestStage {
    PutObject,
@@ -354,7 +383,7 @@ pub enum ConnectionTestStage {
 }

 impl ConnectionTestStage {
-    /// 稳定 wire 值。
+    /// 稳定 wire 值
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
@@ -366,10 +395,10 @@ impl ConnectionTestStage {
    }
 }

-/// 上传到对象存储并期望远端校验的归档 metadata。
+/// 上传到对象存储并期望远端校验的归档 metadata
 ///
 /// `size_bytes` 在上传时不写入 metadata，但 `HeadObject` 会返回远端大小，
-/// 用于与本地归档校验一致。
+/// 用于与本地归档校验一致
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BackupObjectMetadata {
    pub backup_id: String,
@@ -379,7 +408,7 @@ pub struct BackupObjectMetadata {
 }

 impl BackupObjectMetadata {
-    /// 构造上传 metadata。
+    /// 构造上传 metadata
    #[must_use]
    pub const fn new(
        backup_id: String,
@@ -396,7 +425,7 @@ impl BackupObjectMetadata {
    }
 }

-/// 短时下载地址结果。
+/// 短时下载地址结果
 #[derive(Clone, PartialEq, Eq)]
 pub struct DownloadUrlResult {
    pub url: String,
@@ -415,10 +444,11 @@ impl fmt::Debug for DownloadUrlResult {
    }
 }

-/// 备份基础设施错误：只携带稳定错误码与脱敏消息。
+/// 备份基础设施错误：只携带稳定错误码与脱敏消息
 ///
 /// 该类型不构成第二套 kind 枚举；`gateway-admin` 边界统一映射为既有
-/// `AdminErrorKind`。稳定 `error_code` 同时用于任务记录、日志与 UI。
+/// `AdminErrorKind`
+/// 稳定 `error_code` 同时用于任务记录、日志与 UI
 #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
 #[error("{message}")]
 pub struct BackupError {
@@ -427,32 +457,52 @@ pub struct BackupError {
 }

 impl BackupError {
-    /// 构造基础设施错误。
+    /// 构造基础设施错误
    #[must_use]
    pub const fn new(code: &'static str, message: String) -> Self {
        Self { code, message }
    }

-    /// 稳定错误码，例如 `backup.s3_auth_failed`。
+    /// 稳定错误码，例如 `backup.s3_auth_failed`
    #[must_use]
    pub const fn code(&self) -> &'static str {
        self.code
    }

-    /// 脱敏后的可操作消息。
+    /// 脱敏后的可操作消息
    #[must_use]
    pub fn message(&self) -> &str {
        &self.message
    }
+
+    /// 清理失败附加到原始终态，不覆盖上传失败或主动取消的分类
+    #[must_use]
+    pub fn with_cleanup_failure(
+        mut self,
+        stage: &'static str,
+        error: &Self,
+        retry_on_expiration: bool,
+    ) -> Self {
+        let recovery = if retry_on_expiration {
+            "等待备份到期清理"
+        } else {
+            "未安排自动重试"
+        };
+        self.message.push_str(&format!(
+            "；清理阶段 {stage} 失败（{}），{recovery}",
+            error.code()
+        ));
+        self
+    }
 }

-/// 构造稳定错误码常量。
+/// 构造稳定错误码常量
 pub mod code;

-/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`。
+/// 构建对象 key：`{prefix}/YYYY/MM/DD/codex-proxy-rs_{UTC seconds}_{backup id}.dump`
 ///
 /// 规范化规则：prefix 不得为空、不得以前导 `/` 开头、不得包含 `..`、反斜杠或控制字符；
-/// 输出统一使用 `/` 分隔且不含空段。
+/// 输出统一使用 `/` 分隔且不含空段
 pub fn build_object_key(
    prefix: &str,
    backup_id: &str,
@@ -469,22 +519,22 @@ pub fn build_object_key(
    ))
 }

-/// 下载文件名：`codex-proxy-rs_{短 id}.dump`，与对象 key 的文件名一致。
+/// 下载文件名：`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。
+/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex
 #[must_use]
 fn short_backup_id(backup_id: &str) -> String {
    let hex = backup_id.strip_prefix("backup_").unwrap_or(backup_id);
    hex.get(..8).unwrap_or(hex).to_owned()
 }

-/// 规范化并校验对象 prefix。
+/// 规范化并校验对象 prefix
 ///
-/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝。
+/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝
 pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
    if prefix.is_empty() || prefix.starts_with('/') {
        return Err(BackupError::new(
@@ -507,13 +557,13 @@ pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
    Ok(prefix.trim_end_matches('/').to_owned())
 }

-/// 生成新的备份记录 id。
+/// 生成新的备份记录 id
 #[must_use]
 pub fn new_backup_id() -> String {
    format!("backup_{}", Uuid::now_v7().simple())
 }

-/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致。
+/// 从触发类型与计划时间构造可持久化 seed；id 与对象 key 一次生成保持一致
 pub fn build_backup_seed(
    trigger_kind: BackupTriggerKind,
    scheduled_at: Option<DateTime<Utc>>,
@@ -1,8 +1,8 @@
-//! 管理设置页使用的 Codex 客户端下载信息。
+//! 管理设置页使用的 Codex 客户端下载信息

 use chrono::{DateTime, Utc};

-/// Windows 安装包架构。
+/// Windows 安装包架构
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum ClientArchitecture {
    X64,
@@ -19,7 +19,7 @@ impl ClientArchitecture {
    }
 }

-/// 下载地址的可信来源。
+/// 下载地址的可信来源
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientDownloadSource {
    MicrosoftStore,
@@ -36,7 +36,7 @@ impl ClientDownloadSource {
    }
 }

-/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包。
+/// 一个已经过 Host 校验、可以直接交给浏览器下载的安装包
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientDownloadPackage {
    pub architecture: ClientArchitecture,
@@ -48,7 +48,7 @@ pub struct ClientDownloadPackage {
    pub expires_at: Option<DateTime<Utc>>,
 }

-/// Codex Desktop Windows 下载解析结果。
+/// Codex Desktop Windows 下载解析结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CodexDesktopWindowsDownloads {
    pub resolved_at: DateTime<Utc>,
@@ -1,4 +1,4 @@
-//! Client API Key 的 Command、Result 与安全秘密类型。
+//! Client API Key 的 Command、Result 与安全秘密类型

 use std::{collections::BTreeMap, fmt, num::NonZeroU16};

@@ -10,23 +10,40 @@ use gateway_core::{
    routing::{AccountGroupId, ProviderKind},
 };

-use super::{AdminModelError, Revision, account_groups::AccountGroupRef};
+use super::{
+    AdminModelError, Revision, account_groups::AccountGroupRef,
+    plugin_resources::PluginResourceOwner,
+};

 pub type ProviderRequestProfileOverrides =
    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;
 pub type ProviderRequestProfileOverrideUpdates =
    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;

-/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小。
+/// Client Key 关联分组的数量与唯一性约束
+pub fn validate_group_ids(group_ids: &[AccountGroupId]) -> Result<(), AdminModelError> {
+    if group_ids.len() > 1000
+        || group_ids
+            .iter()
+            .collect::<std::collections::BTreeSet<_>>()
+            .len()
+            != group_ids.len()
+    {
+        return Err(AdminModelError::InvalidClientKeyGroups);
+    }
+    Ok(())
+}
+
+/// Client Key 列表保持旧 HTTP 合同允许的完整非零 `u16` 页大小
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ClientKeyPageSize(NonZeroU16);

 impl ClientKeyPageSize {
-    /// 创建 1 至 65535 的 Client Key 页大小。
+    /// 创建 1 至 65535 的 Client Key 页大小
    ///
    /// # Errors
    ///
-    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]。
+    /// `value` 为零时返回 [`AdminModelError::InvalidClientKeyPageSize`]
    pub fn new(value: u16) -> Result<Self, AdminModelError> {
        NonZeroU16::new(value)
            .map(Self)
@@ -39,7 +56,7 @@ impl ClientKeyPageSize {
    }
 }

-/// Client Key 列表排序字段。
+/// Client Key 列表排序字段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientKeySortField {
    Name,
@@ -48,21 +65,21 @@ pub enum ClientKeySortField {
    LastUsedAt,
 }

-/// Client Key 列表排序方向。
+/// Client Key 列表排序方向
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SortDirection {
    Asc,
    Desc,
 }

-/// Client Key 列表排序规则。
+/// Client Key 列表排序规则
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ClientKeySort {
    pub field: ClientKeySortField,
    pub direction: SortDirection,
 }

-/// 与排序字段绑定的游标值。
+/// 与排序字段绑定的游标值
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ClientKeyCursorValue {
    Name(String),
@@ -71,7 +88,7 @@ pub enum ClientKeyCursorValue {
    LastUsedAt(Option<DateTime<Utc>>),
 }

-/// Client Key 的稳定键集游标。
+/// Client Key 的稳定键集游标
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyCursor {
    pub sort: ClientKeySort,
@@ -79,7 +96,7 @@ pub struct ClientKeyCursor {
    pub id: ClientApiKeyId,
 }

-/// Client Key 列表查询。
+/// Client Key 列表查询
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyListQuery {
    pub cursor: Option<ClientKeyCursor>,
@@ -88,7 +105,7 @@ pub struct ClientKeyListQuery {
    pub sort: ClientKeySort,
 }

-/// 不含完整明文 Key 的管理投影。
+/// 不含完整明文 Key 的管理投影
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyRecord {
    pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -106,7 +123,7 @@ pub struct ClientKeyRecord {
    pub updated_at: DateTime<Utc>,
 }

-/// Client Key 列表页。
+/// Client Key 列表页
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyPage {
    pub config_revision: Revision,
@@ -115,7 +132,7 @@ pub struct ClientKeyPage {
    pub next_cursor: Option<ClientKeyCursor>,
 }

-/// 仅在创建或显式读取密钥配置时返回的明文 Key；Debug 隐去明文。
+/// 仅在创建或显式读取密钥配置时返回的明文 Key；Debug 隐去明文
 #[derive(Clone, PartialEq, Eq)]
 pub struct ClientKeySecret {
    pub record: ClientKeyRecord,
@@ -147,7 +164,7 @@ impl fmt::Debug for ClientKeySecret {
    }
 }

-/// API 提交的 Client Key 创建命令。
+/// API 提交的 Client Key 创建命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CreateClientKey {
    pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -159,7 +176,7 @@ pub struct CreateClientKey {
    pub budget: ClientBudgetLimits,
 }

-/// 管理用例生成 ID 与明文后的持久化命令。
+/// 管理用例生成 ID 与明文后的持久化命令
 #[derive(Clone, PartialEq, Eq)]
 pub struct NewClientKey {
    pub request_profile_overrides: ProviderRequestProfileOverrides,
@@ -184,7 +201,7 @@ impl fmt::Debug for NewClientKey {
    }
 }

-/// 修改 Client Key 的公开策略字段。
+/// 修改 Client Key 的公开策略字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct UpdateClientKey {
    pub request_profile_override_updates: ProviderRequestProfileOverrideUpdates,
@@ -197,14 +214,14 @@ pub struct UpdateClientKey {
    pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
 }

-/// 修改 Client Key 启用状态。
+/// 修改 Client Key 启用状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SetClientKeyEnabled {
    pub id: ClientApiKeyId,
    pub enabled: bool,
 }

-/// 管理员选择的金额重置范围。
+/// 管理员选择的金额重置范围
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ClientKeyBudgetPeriod {
    Daily,
@@ -212,20 +229,35 @@ pub enum ClientKeyBudgetPeriod {
    All,
 }

-/// 清零所选窗口已用金额，保留限额、到期时间与历史费用。
+/// 清零所选窗口已用金额，保留限额、到期时间与历史费用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ResetClientKeyBudget {
    pub id: ClientApiKeyId,
    pub period: ClientKeyBudgetPeriod,
 }

-/// 删除 Client Key。
+/// 仅更新指定金额上限；省略的周期保持不变，不修改已用金额或窗口
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UpdateClientKeyBudgetLimits {
+    pub id: ClientApiKeyId,
+    pub daily_limit_usd: Option<gateway_core::metering::Decimal>,
+    pub weekly_limit_usd: Option<gateway_core::metering::Decimal>,
+}
+
+/// 预算变更的调用来源；插件身份由 Runtime 给出，不能从插件请求反序列化
+#[derive(Debug, Clone)]
+pub enum ClientKeyBudgetMutationOrigin {
+    Admin,
+    Plugin(PluginResourceOwner),
+}
+
+/// 删除 Client Key
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteClientKey {
    pub id: ClientApiKeyId,
 }

-/// Client Key 创建结果；完整明文仅存在于该一次性结果中。
+/// Client Key 创建结果；完整明文仅存在于该一次性结果中
 pub struct CreatedClientKey {
    pub config_revision: Revision,
    pub secret: ClientKeySecret,
@@ -241,7 +273,7 @@ impl fmt::Debug for CreatedClientKey {
    }
 }

-/// Client Key 普通写操作结果。
+/// Client Key 普通写操作结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ClientKeyMutation {
    pub config_revision: Revision,
@@ -1,4 +1,4 @@
-//! 进程内账号导入任务；只保存执行所需输入与可公开的结果。
+//! 进程内账号导入任务；只保存执行所需输入与可公开的结果

 use chrono::{DateTime, Utc};
 use gateway_core::{account::ProviderAccountId, routing::ProviderKind};
@@ -17,7 +17,7 @@ pub struct ImportTaskInput {
 #[derive(Debug)]
 pub struct SubmitImportTask {
    pub submission_id: Uuid,
-    /// API 对完整输入计算摘要；用于区分丢失响应后的重试与修改后的新提交。
+    /// API 对完整输入计算摘要；用于区分丢失响应后的重试与修改后的新提交
    pub fingerprint: [u8; 32],
    pub context: MutationContext,
    pub items: Vec<ImportTaskInput>,
@@ -1,10 +1,10 @@
-//! 单页 Key 用量的查询合同；身份范围不由调用方提供。
+//! 单页 Key 用量的查询合同；身份范围不由调用方提供

 use super::{
-    PageSize,
    client_keys::ClientKeyRecord,
    observability::{
-        HealthTimeline, OpsErrorPage, RequestMetricPoint, TimeRange, UsageOverview, UsagePage,
+        HealthTimeline, ObservabilityPageSize, OpsErrorPage, RequestMetricPoint, TimeRange,
+        UsageOverview, UsagePage,
    },
 };

@@ -25,7 +25,7 @@ pub struct KeyUsageRecordsQuery {
    pub usage: KeyUsageQuery,
    pub kind: KeyUsageRecordKind,
    pub current_page: u32,
-    pub page_size: PageSize,
+    pub page_size: ObservabilityPageSize,
 }

 pub struct KeyUsageOverview {
@@ -1,9 +1,11 @@
-//! 管理控制面使用的 Command、Result 与稳定值对象。
+//! 管理控制面使用的 Command、Result 与稳定值对象

 use std::num::{NonZeroU16, NonZeroU64};

 pub mod account_groups;
 pub mod accounts;
+pub mod analytics;
+pub mod audit;
 pub mod auth;
 pub mod backup;
 pub mod client_distribution;
@@ -12,16 +14,18 @@ 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 retention;
 pub mod settings;
 pub mod system;

-/// 管理用例对外返回的稳定错误分类。
+/// 管理用例对外返回的稳定错误分类
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AdminErrorKind {
    Invalid,
@@ -36,12 +40,31 @@ pub enum AdminErrorKind {
    Internal,
 }

-/// 不携带基础设施细节、可安全返回给管理员的管理用例错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+impl AdminErrorKind {
+    #[must_use]
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Invalid => "invalid",
+            Self::Forbidden => "forbidden",
+            Self::Unauthorized => "unauthorized",
+            Self::NotFound => "not_found",
+            Self::Conflict => "conflict",
+            Self::RateLimited => "rate_limited",
+            Self::BadGateway => "bad_gateway",
+            Self::UpstreamResultUnknown => "upstream_result_unknown",
+            Self::Unavailable => "unavailable",
+            Self::Internal => "internal",
+        }
+    }
+}
+
+/// 管理用例的安全消息与内部原因分离，原始来源不进入响应
+#[derive(Debug, Clone, thiserror::Error)]
 #[error("{message}")]
 pub struct AdminError {
    kind: AdminErrorKind,
    message: String,
+    source: Option<gateway_core::error::ErrorSource>,
 }

 impl AdminError {
@@ -50,15 +73,27 @@ impl AdminError {
        Self {
            kind,
            message: message.into(),
+            source: None,
        }
    }

+    #[must_use]
+    pub fn with_source(mut self, source: impl Into<gateway_core::error::ErrorSource>) -> Self {
+        self.source = Some(source.into());
+        self
+    }
+
+    #[must_use]
+    pub fn error_details(&self) -> Option<gateway_core::error::ErrorDetails> {
+        gateway_core::error::ErrorDetails::capture(self.source.as_ref(), None, false)
+    }
+
    #[must_use]
    pub const fn kind(&self) -> AdminErrorKind {
        self.kind
    }

-    /// 返回已脱敏、可公开给管理员的文案。
+    /// 返回已脱敏、可公开给管理员的文案
    #[must_use]
    pub fn message(&self) -> &str {
        &self.message
@@ -105,16 +140,19 @@ impl AdminError {
    }
 }

-/// PostgreSQL 中所有正整数 revision 的管理层表示。
-#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+/// PostgreSQL 中所有正整数 revision 的管理层表示
+#[derive(
+    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Serialize, serde::Deserialize,
+)]
+#[serde(transparent)]
 pub struct Revision(NonZeroU64);

 impl Revision {
-    /// 创建正整数 revision。
+    /// 创建正整数 revision
    ///
    /// # Errors
    ///
-    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]。
+    /// `value` 为零时返回 [`AdminModelError::ZeroRevision`]
    pub fn new(value: u64) -> Result<Self, AdminModelError> {
        NonZeroU64::new(value)
            .map(Self)
@@ -127,18 +165,18 @@ impl Revision {
    }
 }

-/// 管理列表统一使用的受限页大小。
+/// 管理列表统一使用的受限页大小
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PageSize(NonZeroU16);

 impl PageSize {
    pub const MAX: u16 = 200;

-    /// 创建 1 至 200 的页大小。
+    /// 创建 1 至 200 的页大小
    ///
    /// # Errors
    ///
-    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]。
+    /// `value` 不在有效范围时返回 [`AdminModelError::InvalidPageSize`]
    pub fn new(value: u16) -> Result<Self, AdminModelError> {
        if value > Self::MAX {
            return Err(AdminModelError::InvalidPageSize(value));
@@ -154,28 +192,36 @@ impl PageSize {
    }
 }

-/// 可审计管理写操作的发起者。
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// 可审计管理写操作的发起者
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub enum MutationActor {
    AdminSession { admin_user_id: String },
    AdminApiKey,
    System,
 }

-/// 管理写操作必须携带的审计上下文。
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// 管理写操作必须携带的审计上下文
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case", deny_unknown_fields)]
 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("observability page size {0} is outside 1..=100")]
+    InvalidObservabilityPageSize(u16),
+    #[error("account group name or description is invalid")]
+    InvalidAccountGroupFields,
+    #[error("client key group IDs are duplicated or exceed 1000 entries")]
+    InvalidClientKeyGroups,
    #[error("client key page size must be inside 1..=65535")]
    InvalidClientKeyPageSize,
    #[error("request outcome must be 1..=256 bytes without control characters")]
@@ -1,9 +1,18 @@
-//! 插件可见的 Client Key 非秘密资源投影。
+//! 插件可见的 Client Key 非秘密资源投影

 use gateway_core::policy::ClientApiKeyId;
+use gateway_core::routing::AccountGroupId;

 use super::PageSize;

+/// 插件可读取的当前 Key 范围，不含密钥或配置秘密
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PluginClientKeyFacts {
+    pub id: ClientApiKeyId,
+    pub enabled: bool,
+    pub group_ids: Vec<AccountGroupId>,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginClientKeyCursor {
    pub name: String,
@@ -16,7 +25,7 @@ pub struct PluginClientKeyListQuery {
    pub limit: PageSize,
 }

-/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文。
+/// 插件只能发现调用所需的公开身份，不取得 Key 前缀、策略细节或明文
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginClientKey {
    pub id: ClientApiKeyId,
@@ -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,
+}
@@ -1,3 +1,5 @@
+//! 插件分发来源、下载凭据、发行查询与远程安装的数据合同
+
 use std::{fmt, sync::Arc};

 use chrono::{DateTime, Utc};
@@ -17,7 +19,7 @@ pub enum PluginUpdateSource {
    Github { repository: String },
 }

-/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例。
+/// 检查策略只决定查询目标，任何策略都不会自动安装或切换运行实例
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum PluginUpdatePolicy {
@@ -85,7 +87,7 @@ impl fmt::Debug for PluginDistributionEgress {
 #[serde(rename_all = "camelCase")]
 pub struct PluginUpdateCheck {
    pub binding: PluginSourceBinding,
-    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容。
+    /// Release 元数据不是已校验的插件包，不据此声明平台或 SDK 兼容
    pub release: PluginRelease,
 }

@@ -109,7 +111,7 @@ pub enum DownloadPurpose {
    Artifact,
 }

-/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret。
+/// 授权目标以完整 origin 和路径段边界匹配；摘要、名称和列表均不包含 secret
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct SourceCredentialInfo {
@@ -174,7 +176,7 @@ pub struct PluginRelease {
    pub expires_at: DateTime<Utc>,
 }

-/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用。
+/// 下载意图不承载凭据；引用在 Admin 中解析后只交给 Host 的本次调用
 #[derive(Debug, Clone, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum RemotePluginLocation {
@@ -200,7 +202,7 @@ pub struct RemotePluginVerify {
    pub credential_ids: Vec<String>,
    #[serde(default)]
    pub outbound_proxy_id: Option<String>,
-    /// 更新已有插件时锁定身份；首次安装从包内清单读取。
+    /// 更新已有插件时锁定身份；首次安装从包内清单读取
    pub expected_plugin_id: Option<String>,
 }

@@ -222,7 +224,7 @@ pub struct DownloadedPlugin {
    pub source: PluginSource,
 }

-/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备。
+/// 只读包校验结果，不代表实例配置、授权或私有状态已完成运行时准备
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct VerifiedPluginArtifact {
@@ -1,3 +1,5 @@
+//! 插件实例配置、能力绑定、运行状态与版本切换的数据合同
+
 use std::collections::BTreeMap;

 use secrecy::SecretString;
@@ -5,12 +7,6 @@ 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 {
@@ -26,6 +22,9 @@ pub struct PluginCapabilityBinding {
    pub stage: String,
    pub order: i32,
    pub failure_policy: PluginFailurePolicy,
+    /// 观察绑定选择事件类型；其他能力不设置事件
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub event: Option<String>,
    #[serde(default)]
    pub client_key_ids: Vec<String>,
    #[serde(default)]
@@ -38,7 +37,7 @@ pub struct PluginCapabilityBinding {
    pub identity_bindings: Vec<PluginFrontendIdentityBinding>,
 }

-/// 外部 principal 到既有 Client Key 的显式宿主映射。
+/// 外部 principal 到既有 Client Key 的显式宿主映射
 #[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct PluginFrontendIdentityBinding {
@@ -56,7 +55,7 @@ impl std::fmt::Debug for PluginFrontendIdentityBinding {
    }
 }

-/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置。
+/// 配置和 secret 分离；Debug 与 Serialize 不得无意展开实例配置
 #[derive(Clone)]
 pub struct PluginInstance {
    pub id: String,
@@ -66,7 +65,6 @@ pub struct PluginInstance {
    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,
 }
@@ -82,7 +80,7 @@ pub struct PluginInstanceMutation {
    pub instance: PluginInstance,
 }

-/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置。
+/// 控制面展示的单实例运行状态；它描述当前进程观察到的事实，不替代持久启用配置
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PluginInstanceRuntimeStatus {
    Disabled,
@@ -95,14 +93,14 @@ pub enum PluginInstanceRuntimeStatus {
    Draining,
 }

-/// 已脱敏且可安全返回给管理员的运行失败摘要。
+/// 已脱敏且可安全返回给管理员的运行失败摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstanceRuntimeFailure {
    pub code: String,
    pub message: String,
 }

-/// 当前发布视图与代次索引的只读诊断。
+/// 当前发布视图与代次索引的只读诊断
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginInstanceRuntime {
    pub status: PluginInstanceRuntimeStatus,
@@ -112,9 +110,24 @@ pub struct PluginInstanceRuntime {
    pub draining_revisions: Vec<u64>,
 }

+/// 可继续运行的旧接口提示，与无法启用的兼容性错误分开
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct PluginApiDeprecation {
+    pub capability: String,
+    pub version: u32,
+    pub replacement_version: u32,
+    pub introduced_in: Option<String>,
+    pub remaining_releases: u32,
+    pub migration: String,
+}
+
 pub struct PluginInstanceView {
    pub instance: PluginInstance,
    pub configuration_required: bool,
+    pub compatibility_warning: Option<String>,
+    pub load_error: Option<String>,
+    pub api_deprecations: Vec<PluginApiDeprecation>,
    pub running: bool,
    pub published_revision: Option<u64>,
    pub runtime: PluginInstanceRuntime,
@@ -123,18 +136,18 @@ pub struct PluginInstanceView {
 #[derive(Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct ConfigurePluginInstance {
-    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口。
+    /// 创建草稿固定一个 UUID，重试复用同一配置，不能作为编辑已有配置的入口
    pub creation_id: Option<String>,
-    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容。
+    /// 编辑时检查用户看到的配置版本，避免覆盖另一窗口已经保存的内容
    pub expected_revision: Option<u64>,
-    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换。
+    /// 管理员确认停用的同插件配置，与当前配置在同一事务中切换
    #[serde(default)]
    pub replace_instances: Vec<PluginInstanceReplacement>,
    pub name: String,
    pub artifact_sha256: String,
    pub enabled: bool,
    pub configuration: serde_json::Value,
-    /// 缺省保留旧值；显式空对象清除全部 secret。
+    /// 缺省保留旧值；显式空对象清除全部 secret
    pub secrets: Option<BTreeMap<String, SecretString>>,
    pub bindings: Vec<PluginCapabilityBinding>,
 }
@@ -146,7 +159,7 @@ pub struct PluginInstanceReplacement {
    pub expected_revision: u64,
 }

-/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验。
+/// 恢复已安装旧版本的配置快照，并重新通过目标版本校验
 #[derive(Debug, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct RollbackPluginInstance {
@@ -162,7 +175,7 @@ pub struct PluginRollbackTarget {
    pub platforms: Vec<String>,
 }

-/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性。
+/// 静态候选不启动插件；实际回滚仍须复验配置、平台和私有状态兼容性
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginRollbackPlan {
@@ -171,7 +184,7 @@ pub struct PluginRollbackPlan {
    pub targets: Vec<PluginRollbackTarget>,
 }

-/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize。
+/// 版本配置快照只用于服务端恢复，敏感值不实现 Debug 或 Serialize
 #[derive(Clone)]
 pub struct PluginVersionConfiguration {
    pub configuration: serde_json::Value,
@@ -179,7 +192,7 @@ pub struct PluginVersionConfiguration {
    pub bindings: Vec<PluginCapabilityBinding>,
 }

-/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置。
+/// 切换版本的只读草稿，不包含密钥值，也不会启动插件或写入配置
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginVersionPlan {
@@ -1,8 +1,10 @@
+//! 插件管理页面、静态资源、请求与授权回调的数据合同
+
 use std::sync::Arc;

 use serde::{Deserialize, Serialize};

-/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份。
+/// 页面和业务调用绑定同一实例版本；制品摘要单独作为不可变资源身份
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
 pub struct PluginManagementTarget {
@@ -37,7 +39,7 @@ pub struct StartPluginManagementCallback {
    pub ttl_seconds: u32,
 }

-/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志。
+/// state 是短期一次性秘密，只交给发起登录的管理员，不进入 Debug 或日志
 #[derive(Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct PluginManagementCallbackTicket {
@@ -72,12 +74,13 @@ pub struct PluginManagementResource {
    pub public: bool,
 }

-/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志。
+/// 原始正文可能含业务数据，不能派生内容型 Debug 或写入诊断日志
 pub struct PluginManagementRequest {
    pub method: String,
    pub path: String,
    pub query: String,
    pub content_type: Option<String>,
+    pub headers: Vec<gateway_core::engine::middleware::MiddlewareHeader>,
    pub body: Vec<u8>,
    pub request_id: String,
 }
@@ -85,5 +88,6 @@ pub struct PluginManagementRequest {
 pub struct PluginManagementResponse {
    pub status: u16,
    pub content_type: String,
+    pub headers: Vec<gateway_core::engine::middleware::MiddlewareHeader>,
    pub body: Arc<[u8]>,
 }
@@ -1,3 +1,5 @@
+//! 插件制品元数据、宿主兼容性与管理领域模型的公共入口
+
 use std::{
    collections::{BTreeMap, BTreeSet},
    sync::Arc,
@@ -13,7 +15,7 @@ pub mod management;
 pub mod official;
 pub mod state;

-/// 一个宿主发行版明确承诺支持的插件能力版本。
+/// 一个宿主发行版明确承诺支持的插件能力版本
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct PluginHostCapability {
@@ -21,7 +23,7 @@ pub struct PluginHostCapability {
    pub versions: Vec<u32>,
 }

-/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明。
+/// 随宿主发行物封口的插件合同；Runtime 与发布清单共用这一份声明
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(deny_unknown_fields)]
 pub struct PluginHostCompatibility {
@@ -29,19 +31,17 @@ pub struct PluginHostCompatibility {
    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
+        if self.schema_version != 2
            || !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;
        }
@@ -53,10 +53,7 @@ impl PluginHostCompatibility {
        }) {
            return false;
        }
-        let mut permissions = BTreeSet::new();
-        !self.permissions.iter().any(|permission| {
-            !valid_identifier(permission) || !permissions.insert(permission.as_str())
-        })
+        true
    }

    #[must_use]
@@ -65,11 +62,6 @@ impl PluginHostCompatibility {
            .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 {
@@ -111,17 +103,16 @@ fn valid_plugin_segment(value: &str) -> bool {
            .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || byte == b'-')
 }

-/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret。
+/// 已安装包对目标宿主的静态要求；不包含包体、配置或 secret
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginCompatibilityRequirements {
    pub host_version: String,
    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 {
@@ -129,7 +120,7 @@ pub struct PluginSourceEgress {
    pub revision: u64,
 }

-/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用。
+/// 安装来源只保存公开定位信息，下载凭据和出站代理通过独立记录引用
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(tag = "kind", rename_all = "snake_case", deny_unknown_fields)]
 pub enum PluginSource {
@@ -175,18 +166,21 @@ impl PluginSource {
    }
 }

-/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份。
+/// 管理端保留的单项贡献声明；map key 是能力标识，`id` 是实例绑定引用的扩展项身份
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[serde(rename_all = "camelCase")]
 pub struct PluginContribution {
    pub id: String,
    pub version: u32,
+    #[serde(default)]
    pub stages: Vec<String>,
+    #[serde(default)]
    pub input_formats: Vec<String>,
+    #[serde(default)]
    pub output_formats: Vec<String>,
 }

-/// 制品清单中的展示图标；路径只用于选择已校验的包资源。
+/// 制品清单中的展示图标；路径只用于选择已校验的包资源
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(untagged)]
 pub enum PluginArtifactIcon {
@@ -195,7 +189,6 @@ pub enum PluginArtifactIcon {
 }

 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(deny_unknown_fields)]
 pub struct PluginArtifactIconVariants {
    pub light: String,
    pub dark: String,
@@ -207,24 +200,17 @@ pub enum PluginIconTheme {
    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,
-}
-
+/// 已校验制品的持久化投影；读取时忽略未知字段，可选字段缺省沿用清单语义
+/// 身份与执行所需事实仍为必填，包清单及协议版本由 Runtime 独立校验
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[serde(rename_all = "camelCase")]
 pub struct PluginArtifactMetadata {
    pub plugin_id: String,
    pub version: String,
@@ -239,14 +225,19 @@ pub struct PluginArtifactMetadata {
    #[serde(default)]
    pub icon: Option<PluginArtifactIcon>,
    pub contributes: BTreeMap<String, PluginContribution>,
-    pub requested_permissions: Vec<String>,
+    #[serde(default = "empty_configuration_schema")]
    pub configuration_schema: serde_json::Value,
+    #[serde(default)]
    pub secret_fields: Vec<String>,
    #[serde(default)]
    pub state_namespaces: Vec<state::PluginStateSchema>,
 }

-/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据。
+fn empty_configuration_schema() -> serde_json::Value {
+    serde_json::json!({})
+}
+
+/// 由包检查端口产生的不可变制品；不派生 Debug，包内可能含敏感用户数据
 #[derive(Clone)]
 pub struct InspectedPluginArtifact {
    pub metadata: PluginArtifactMetadata,
@@ -1,13 +1,15 @@
+//! 官方插件发行身份与导入命令
+
 use super::super::Revision;

-/// 编译进宿主二进制的发行身份；不能由运行时配置或插件清单覆盖。
+/// 编译进宿主二进制的发行身份；不能由运行时配置或插件清单覆盖
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OfficialPluginReleaseIdentity {
    pub gateway_version: String,
    pub gateway_git_sha: String,
 }

-/// 启动时导入官方制品的结果；导入只持久化制品，不创建或启用实例。
+/// 启动时导入官方制品的结果；导入只持久化制品，不创建或启用实例
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct OfficialPluginImport {
    pub artifacts: usize,
@@ -1,12 +1,14 @@
+//! 插件私有状态的归属、代次隔离与迁移数据合同
+
 use std::{collections::BTreeMap, fmt};

 use serde::{Deserialize, Serialize};

 use crate::model::Revision;

-/// 已由 Runtime 校验的命名空间 schema 与配额事实。
+/// 已由 Runtime 校验的命名空间 schema 与配额事实
 #[derive(Clone, PartialEq, Serialize, Deserialize)]
-#[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[serde(rename_all = "camelCase")]
 pub struct PluginStateSchema {
    pub namespace: String,
    pub schema_version: u32,
@@ -42,7 +44,7 @@ pub struct PluginStateConfiguration {
    pub namespaces: Vec<PluginStateSchema>,
 }

-/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据。
+/// 与实例保存同事务提交的状态配置；transition 只引用已完成的 staging 数据
 #[derive(Clone, Default)]
 pub struct PluginStateCommit {
    pub configuration: PluginStateConfiguration,
@@ -57,7 +59,8 @@ pub struct PluginStateOwnerRequest {
    pub configuration: PluginStateConfiguration,
 }

-/// Store 签发的实例私有状态 fence。插件协议中从不传输这些字段。
+/// Store 签发的实例私有状态 fence
+/// 插件协议中从不传输这些字段
 #[derive(Clone)]
 pub struct PluginStateOwner {
    instance_id: String,
@@ -136,7 +139,7 @@ impl PluginStateNamespaceOwner {
    }
 }

-/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`。
+/// 私有值可能含插件自己的敏感状态，故意不实现 `Debug`
 #[derive(Clone)]
 pub struct PluginStateRecord {
    pub key: String,
@@ -149,7 +152,7 @@ pub struct PutPluginState {
    pub namespace: String,
    pub key: String,
    pub value: serde_json::Value,
-    /// `None` 是 create-only；已有记录必须提交精确版本。
+    /// `None` 是 create-only；已有记录必须提交精确版本
    pub expected_version: Option<u64>,
 }

@@ -188,7 +191,7 @@ pub struct ApplyPluginStateMigration {
    pub transition_id: String,
    pub namespace: String,
    pub cursor: Option<String>,
-    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对。
+    /// Runtime 刚读取的有序源键；Store 会在写入前重新读取并逐项比对
    pub expected_keys: Vec<String>,
    pub changes: Vec<PluginStateMigrationChange>,
 }
@@ -1,9 +1,9 @@
-//! 全局模型定价的管理合同。
+//! 全局模型定价的管理合同

 use gateway_core::metering::{ModelPriceOverride, PricingOverrides};
 use std::collections::{BTreeMap, BTreeSet};

-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub struct PricingCatalog {
    pub defaults: PricingOverrides,
    pub overrides: PricingOverrides,
@@ -27,6 +27,7 @@ pub struct PricingSyncPreview {

 #[derive(Debug, Clone, PartialEq, Eq, serde::Deserialize)]
 #[serde(rename_all = "camelCase", deny_unknown_fields)]
+#[derive(serde::Serialize)]
 pub struct SyncPricing {
    pub preview: PricingSyncPreview,
    pub models: BTreeMap<String, BTreeSet<String>>,
@@ -34,7 +35,7 @@ pub struct SyncPricing {

 pub type PricingSyncChanges = BTreeMap<String, BTreeMap<String, Option<ModelPriceOverride>>>;

-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub enum PricingChange {
    Replace(ModelPriceOverride),
    Multiplier(u32),
@@ -42,7 +43,7 @@ pub enum PricingChange {
    Delete,
 }

-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
 pub struct UpdatePricing {
    pub provider: String,
    pub models: Vec<String>,
@@ -1,4 +1,4 @@
-//! Provider 管理能力交换的中立 Command 与 Result。
+//! Provider 管理能力交换的中立 Command 与 Result

 use std::{fmt, pin::Pin};

@@ -22,7 +22,7 @@ use super::{
    },
 };

-/// Provider-owned JSON；公共层只搬运且 Debug 不输出值。
+/// Provider-owned JSON；公共层只搬运且 Debug 不输出值
 #[derive(Clone, PartialEq)]
 pub struct ProviderDocument(OpaqueProviderData);

@@ -32,7 +32,7 @@ impl ProviderDocument {
        Self(data)
    }

-    /// 仅具体 Provider 可以解释内部字段。
+    /// 仅具体 Provider 可以解释内部字段
    #[must_use]
    pub const fn expose_to_provider(&self) -> &OpaqueProviderData {
        &self.0
@@ -50,14 +50,14 @@ impl fmt::Debug for ProviderDocument {
    }
 }

-/// Provider credential 详情。
+/// Provider credential 详情
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDetails {
    pub config_revision: Revision,
    pub credential: AccountRecord,
 }

-/// Provider 正式文档批量导入命令。
+/// Provider 正式文档批量导入命令
 pub struct ImportCredentials {
    pub outbound_proxy_id: Option<String>,
    pub settings: Option<AccountImportSettings>,
@@ -75,14 +75,14 @@ impl fmt::Debug for ImportCredentials {
    }
 }

-/// 批量导入提交结果。
+/// 批量导入提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialImportResult {
    pub config_revision: Revision,
    pub credential_ids: Vec<ProviderAccountId>,
 }

-/// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文。
+/// Provider 解析导入文档时只接收不透明文档，不接触 revision 或审计上下文
 pub struct PrepareCredentialImport {
    pub default_outbound_proxy: Option<gateway_core::account::OutboundProxy>,
    pub document: ProviderDocument,
@@ -97,7 +97,7 @@ impl fmt::Debug for PrepareCredentialImport {
    }
 }

-/// Provider 已验证、可由 Store 原子创建的一份 credential。
+/// Provider 已验证、可由 Store 原子创建的一份 credential
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialCreate {
    pub model_access: Option<gateway_core::account::AccountModelAccess>,
@@ -119,14 +119,14 @@ pub struct PreparedCredentialCreate {
    pub credential_observed_at: DateTime<Utc>,
 }

-/// Provider 对一份导入文档的完整验证结果。
+/// Provider 对一份导入文档的完整验证结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialImport {
    pub provider_kind: ProviderKind,
    pub credentials: Vec<PreparedCredentialCreate>,
 }

-/// Admin 交给 Store 的导入事务命令。
+/// Admin 交给 Store 的导入事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialImportCommit {
    pub outbound_proxy: Option<super::proxies::ImportProxyBinding>,
@@ -134,7 +134,7 @@ pub struct CredentialImportCommit {
    pub prepared: PreparedCredentialImport,
 }

-/// OAuth pending owner 的中立身份；不编码具体 Provider 的 Redis key 或 JSON。
+/// OAuth pending owner 的中立身份；不编码具体 Provider 的 Redis key 或 JSON
 #[derive(Clone, PartialEq, Eq)]
 pub enum AuthorizationOwner {
    AdminSession { admin_user_id: String },
@@ -148,7 +148,7 @@ impl fmt::Debug for AuthorizationOwner {
    }
 }

-/// Provider 写入 pending payload 与 Redis owner binding 所需的全部中立字段。
+/// Provider 写入 pending payload 与 Redis owner binding 所需的全部中立字段
 #[derive(Clone, PartialEq, Eq)]
 pub struct AuthorizationOwnerBinding {
    owner: AuthorizationOwner,
@@ -193,17 +193,17 @@ impl fmt::Debug for AuthorizationOwnerBinding {
    }
 }

-/// OAuth 完成时应创建新账号还是 CAS 更新既有 credential。
+/// OAuth 完成时应创建新账号还是 CAS 更新既有 credential
 ///
 /// 重新授权只绑定稳定的账号身份：credential revision 由服务端在临近写入时读取，
-/// 长流程期间的后台刷新不得让恢复操作失效。
+/// 长流程期间的后台刷新不得让恢复操作失效
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AuthorizationMutationTarget {
    Create { name: String },
    Reauthorize { account_id: ProviderAccountId },
 }

-/// 必须完整进入 Provider opaque pending payload、并在 complete 后原样恢复的事务信封。
+/// 必须完整进入 Provider opaque pending payload、并在 complete 后原样恢复的事务信封
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PendingAuthorizationMutation {
    provider_kind: ProviderKind,
@@ -269,7 +269,7 @@ impl PendingAuthorizationMutation {
 }

 impl PendingAuthorizationMutation {
-    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持。
+    /// 编码 v1 中立事务字段；版本号的位置和 Provider 私有外层文档由 adapter 保持
    #[must_use]
    pub fn to_storage_v1(&self) -> Map<String, Value> {
        let target = match &self.target {
@@ -311,11 +311,11 @@ impl PendingAuthorizationMutation {
        document
    }

-    /// 恢复 adapter 已确认版本为 v1 的中立事务字段。
+    /// 恢复 adapter 已确认版本为 v1 的中立事务字段
    ///
    /// # Errors
    ///
-    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容。
+    /// 文档字段、Provider kind 或账号身份非法时返回错误，不携带原始 pending 内容
    pub fn from_storage_v1(value: Value) -> Result<Self, AdminError> {
        let invalid = || AdminError::invalid("invalid pending authorization mutation");
        let document: StoredAuthorizationMutationV1 =
@@ -385,7 +385,7 @@ enum StoredAuthorizationOwnerV1 {
    System,
 }

-/// Provider 授权请求。
+/// Provider 授权请求
 #[derive(Debug, Clone, PartialEq)]
 pub struct StartAuthorization {
    pub context: MutationContext,
@@ -394,7 +394,7 @@ pub struct StartAuthorization {
    pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }

-/// OAuth 流程启动结果。
+/// OAuth 流程启动结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AuthorizationStarted {
    pub flow_id: String,
@@ -402,35 +402,37 @@ pub struct AuthorizationStarted {
    pub expires_at: DateTime<Utc>,
 }

-/// refresh/rotate/reauthorize 的 lease 或 completion 生命周期。
+/// refresh/rotate/reauthorize 的 lease 或 completion 生命周期
 ///
-/// 该 guard 不可 Clone。Admin 只能在 Store CAS 与审计事务成功后调用 `finish`；失败路径直接
-/// drop，使 Provider 可以释放 lease 或执行补偿。
+/// 该 guard 不可 Clone
+/// Admin 只能在 Store CAS 与审计事务成功后调用 `finish`；失败路径直接
+/// drop，使 Provider 可以释放 lease 或执行补偿
 pub trait CredentialCommitGuard: Send + 'static {
    fn finish(self: Box<Self>);
 }

-/// OAuth pending claim 在 Store 事务结果确定后执行的显式结算动作。
+/// OAuth pending claim 在 Store 事务结果确定后执行的显式结算动作
 ///
 /// OAuth provider 必须在 credential 准备阶段持有 claim：Store 提交成功后消费 flow，提交或
-/// 校验失败后释放 flow。异步结算不能依赖 `Drop`，否则请求提前返回会让同一授权流无谓地
-/// 进入短暂的不可重试状态。
+/// 校验失败后释放 flow
+/// 异步结算不能依赖 `Drop`，否则请求提前返回会让同一授权流无谓地
+/// 进入短暂的不可重试状态
 #[async_trait]
 pub trait AuthorizationCommitGuard: Send + 'static {
-    /// Store 已提交 OAuth credential 后消费对应的一次性 flow。
+    /// Store 已提交 OAuth credential 后消费对应的一次性 flow
    async fn commit(self: Box<Self>) -> Result<(), AdminError>;

-    /// Store 未提交 OAuth credential 时释放 claim，允许同一 flow 重试。
+    /// Store 未提交 OAuth credential 时释放 claim，允许同一 flow 重试
    async fn abort(self: Box<Self>) -> Result<(), AdminError>;
 }

-/// OAuth complete 后由 Provider 返回的准备结果；Store 仍是唯一提交者。
+/// OAuth complete 后由 Provider 返回的准备结果；Store 仍是唯一提交者
 pub enum PreparedAuthorizationCredential {
    Create(Box<PreparedCredentialCreate>),
    Reauthorize(Box<PreparedCredentialRotation>),
 }

-/// Provider 从 opaque pending payload 恢复的信封与已验证 credential 必须一起返回。
+/// Provider 从 opaque pending payload 恢复的信封与已验证 credential 必须一起返回
 pub struct PreparedAuthorizationCommit {
    pub pending: PendingAuthorizationMutation,
    pub credential: PreparedAuthorizationCredential,
@@ -447,14 +449,14 @@ impl fmt::Debug for PreparedAuthorizationCommit {
    }
 }

-/// Store 可持久化的 OAuth credential facts，不携带 Provider guard。
+/// Store 可持久化的 OAuth credential facts，不携带 Provider guard
 #[derive(Debug, Clone, PartialEq)]
 pub enum AuthorizationCredentialCommit {
    Create(Box<PreparedCredentialCreate>),
    Reauthorize(Box<PreparedCredentialRotationFacts>),
 }

-/// Admin 交给 Store 的 OAuth 原子事务命令。
+/// Admin 交给 Store 的 OAuth 原子事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct AuthorizationCommit {
    pub key: AuthorizationReceiptKey,
@@ -463,7 +465,7 @@ pub struct AuthorizationCommit {
    pub credential: AuthorizationCredentialCommit,
 }

-/// 回执以 Provider、授权流和管理员身份绑定；不持久化原始 flow 或回调材料。
+/// 回执以 Provider、授权流和管理员身份绑定；不持久化原始 flow 或回调材料
 #[derive(Clone, PartialEq, Eq, PartialOrd, Ord)]
 pub struct AuthorizationReceiptKey {
    provider_kind: ProviderKind,
@@ -531,10 +533,10 @@ pub struct AuthorizationCommitResult {
    pub newly_committed: bool,
 }

-/// OAuth 准备结果拆解后的 Store 命令与两个结算 guard。
+/// OAuth 准备结果拆解后的 Store 命令与两个结算 guard
 ///
 /// Store 成功时先结束 credential guard，再消费 OAuth claim；失败时丢弃 credential guard 并
-/// 释放 OAuth claim，使同一授权流可以重试。
+/// 释放 OAuth claim，使同一授权流可以重试
 pub(crate) struct AuthorizationCommitSettlement {
    pub(crate) command: AuthorizationCommit,
    pub(crate) credential_guard: Option<Box<dyn CredentialCommitGuard>>,
@@ -554,7 +556,7 @@ impl PreparedAuthorizationCommit {
        }
    }

-    /// 让 OAuth claim 覆盖准备完成到 Store 事务结算之间的全部窗口。
+    /// 让 OAuth claim 覆盖准备完成到 Store 事务结算之间的全部窗口
    #[must_use]
    pub fn with_authorization_guard(mut self, guard: Box<dyn AuthorizationCommitGuard>) -> Self {
        self.authorization_guard = Some(guard);
@@ -599,7 +601,7 @@ impl PreparedAuthorizationCommit {
    }
 }

-/// 完成 Provider OAuth 流程。
+/// 完成 Provider OAuth 流程
 #[derive(Clone, PartialEq, Eq)]
 pub struct CompleteAuthorization {
    pub settings: Option<AccountImportSettings>,
@@ -619,14 +621,14 @@ impl fmt::Debug for CompleteAuthorization {
    }
 }

-/// Credential 生命周期写操作。
+/// Credential 生命周期写操作
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialMutation {
    pub context: MutationContext,
    pub account_id: ProviderAccountId,
 }

-/// Credential 写入提交结果。
+/// Credential 写入提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialMutationResult {
    pub config_revision: Revision,
@@ -634,28 +636,28 @@ pub struct CredentialMutationResult {
    pub credential_revision: Option<Revision>,
 }

-/// 同一 Provider 管理范围内的 credential 批量删除。
+/// 同一 Provider 管理范围内的 credential 批量删除
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDeletion {
    pub context: MutationContext,
    pub account_ids: Vec<ProviderAccountId>,
 }

-/// Credential 批量删除提交结果。
+/// Credential 批量删除提交结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CredentialDeletionResult {
    pub config_revision: Revision,
    pub account_ids: Vec<ProviderAccountId>,
 }

-/// Provider-owned token 轮换命令。
+/// Provider-owned token 轮换命令
 pub struct RotateCredential {
    pub mutation: CredentialMutation,
    pub provider_material: ProviderDocument,
    pub settings: Option<super::accounts::UpdateAccount>,
 }

-/// Provider 校验手工轮换材料时所需的非事务输入。
+/// Provider 校验手工轮换材料时所需的非事务输入
 pub struct PrepareCredentialRotation {
    pub account: AccountRecord,
    pub provider_material: ProviderDocument,
@@ -671,7 +673,7 @@ impl fmt::Debug for PrepareCredentialRotation {
    }
 }

-/// Provider 已验证、可由 Store 以 credential revision CAS 原子提交的轮换 facts。
+/// Provider 已验证、可由 Store 以 credential revision CAS 原子提交的轮换 facts
 #[derive(Debug, Clone, PartialEq)]
 pub struct PreparedCredentialRotationFacts {
    pub account_id: ProviderAccountId,
@@ -681,9 +683,9 @@ pub struct PreparedCredentialRotationFacts {
    pub name: String,
    pub email: Option<String>,
    pub plan_type: Option<String>,
-    /// Token 刷新保留提交时的资料，不以准备阶段的副本覆盖新套餐。
+    /// Token 刷新保留提交时的资料，不以准备阶段的副本覆盖新套餐
    pub preserve_profile: bool,
-    /// 连接配置变更保留当前凭据健康状态与错误事实。
+    /// 连接配置变更保留当前凭据健康状态与错误事实
    pub preserve_credential_state: bool,
    pub provider_material: ProviderDocument,
    pub has_refresh_token: bool,
@@ -691,7 +693,7 @@ pub struct PreparedCredentialRotationFacts {
    pub next_refresh_at: Option<DateTime<Utc>>,
 }

-/// Provider 返回的轮换准备结果；guard 必须覆盖后续 Store CAS 与审计事务。
+/// Provider 返回的轮换准备结果；guard 必须覆盖后续 Store CAS 与审计事务
 pub struct PreparedCredentialRotation {
    facts: PreparedCredentialRotationFacts,
    guard: Box<dyn CredentialCommitGuard>,
@@ -706,7 +708,7 @@ impl PreparedCredentialRotation {
        Self { facts, guard }
    }

-    /// 仅修改连接配置时，不把配置更新视为凭据恢复成功。
+    /// 仅修改连接配置时，不把配置更新视为凭据恢复成功
    #[must_use]
    pub fn preserving_credential_state(mut self) -> Self {
        self.facts.preserve_credential_state = true;
@@ -739,7 +741,7 @@ impl fmt::Debug for PreparedCredentialRotation {
    }
 }

-/// Admin 交给 Store 的轮换或 refresh 事务命令。
+/// Admin 交给 Store 的轮换或 refresh 事务命令
 #[derive(Debug, Clone, PartialEq)]
 pub struct CredentialRotationCommit {
    pub prepared: PreparedCredentialRotationFacts,
@@ -757,16 +759,16 @@ impl fmt::Debug for RotateCredential {
    }
 }

-/// 通用账号用量能否可靠归属到一个 Provider quota 窗口。
+/// 通用账号用量能否可靠归属到一个 Provider quota 窗口
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum QuotaLocalUsageAttribution {
-    /// 窗口覆盖账号的全部请求，可按账号与时间范围聚合。
+    /// 窗口覆盖账号的全部请求，可按账号与时间范围聚合
    AccountWide,
-    /// 窗口需要 Provider / 模型级归属，通用账号聚合不可用。
+    /// 窗口需要 Provider / 模型级归属，通用账号聚合不可用
    Unavailable,
 }

-/// Provider quota bucket 中窗口的官方位置语义。
+/// Provider quota bucket 中窗口的官方位置语义
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProviderQuotaWindowRole {
    Primary,
@@ -785,7 +787,7 @@ impl ProviderQuotaWindowRole {
    }
 }

-/// 一个 Provider quota 窗口的公共投影。
+/// 一个 Provider quota 窗口的公共投影
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuotaWindow {
    pub key: String,
@@ -803,14 +805,14 @@ pub struct ProviderQuotaWindow {
    pub provider_data: Option<ProviderDocument>,
 }

-/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板。
+/// 账号用量统计周期，按周优先、月次之选择；短期限流窗口不参与统计面板
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum AccountUsagePeriod {
    Weekly,
    Monthly,
 }

-/// Provider 解释 quota 所需的公共请求事实。
+/// Provider 解释 quota 所需的公共请求事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderQuotaRequest {
    pub account_id: ProviderAccountId,
@@ -818,20 +820,29 @@ pub struct ProviderQuotaRequest {
    pub rolling_usage: Option<AccountUsage>,
 }

-/// Provider 已解析的 quota 结果及其不透明差异字段。
+/// Provider 已解析的 quota 结果及其不透明差异字段
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderQuota {
-    /// 上游额度响应明确提供的套餐，可用于补全账号展示。
+    /// 上游额度响应明确提供的套餐，可用于补全账号展示
    pub plan_type: Option<String>,
    pub observed_at: Option<DateTime<Utc>>,
    pub refresh_token_expires_at: Option<DateTime<Utc>>,
    pub windows: Vec<ProviderQuotaWindow>,
-    /// 展示用快照级触顶事实（顶层或任一窗口触顶）；不参与账号五态派生。
+    pub credits: Option<ProviderQuotaCredits>,
+    /// 展示用快照级触顶事实（顶层或任一窗口触顶）；不参与账号五态派生
    pub limit_reached: bool,
    pub provider_data: Option<ProviderDocument>,
 }

-/// 空值和 `unknown` 代表未提供套餐；新的套餐标识仍按明确值保留。
+/// 上游点数余额的展示事实，保留原始十进制文本以避免精度损失
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ProviderQuotaCredits {
+    pub has_credits: bool,
+    pub unlimited: bool,
+    pub balance: Option<String>,
+}
+
+/// 空值和 `unknown` 代表未提供套餐；新的套餐标识仍按明确值保留
 pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
    value.filter(|value| {
        let value = value.trim();
@@ -839,7 +850,7 @@ pub(crate) fn explicit_plan_type(value: Option<&str>) -> Option<&str> {
    })
 }

-/// 按需查询的订阅周期，不参与额度或账号可用性判断。
+/// 按需查询的订阅周期，不参与额度或账号可用性判断
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderSubscription {
    pub starts_at: Option<DateTime<Utc>>,
@@ -850,14 +861,14 @@ pub struct ProviderSubscription {
    pub observed_at: DateTime<Utc>,
 }

-/// 按需汇聚的个人信息；资料查询失败不丢弃可用的订阅结果。
-#[derive(Debug, Clone, PartialEq)]
+/// 按需汇聚的个人信息；资料查询失败不丢弃可用的订阅结果
+#[derive(Debug, Clone)]
 pub struct AccountPersonalInfo {
    pub profile: Result<ProviderProfileStatistics, AdminError>,
    pub subscription: Option<ProviderSubscription>,
 }

-/// Provider 官方个人资料中的累计摘要。
+/// Provider 官方个人资料中的累计摘要
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileStatisticsSummary {
    pub total_text_tokens: Option<u64>,
@@ -867,14 +878,14 @@ pub struct ProviderProfileStatisticsSummary {
    pub longest_streak_days: Option<u64>,
 }

-/// Provider 官方个人资料中的单日 Token bucket。
+/// Provider 官方个人资料中的单日 Token bucket
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileDailyUsage {
    pub date: NaiveDate,
    pub tokens: u64,
 }

-/// Provider 官方个人资料中的插件或 Skill 调用排行。
+/// Provider 官方个人资料中的插件或 Skill 调用排行
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderProfileInvocation {
    pub invocation_type: String,
@@ -885,7 +896,7 @@ pub struct ProviderProfileInvocation {
    pub usage_count: Option<u64>,
 }

-/// Provider 官方个人资料中的活动洞察。
+/// Provider 官方个人资料中的活动洞察
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderProfileActivityInsights {
    pub fast_mode_percent: Option<f64>,
@@ -897,7 +908,7 @@ pub struct ProviderProfileActivityInsights {
    pub invocations: Option<Vec<ProviderProfileInvocation>>,
 }

-/// Provider 已解释的官方个人资料统计。
+/// Provider 已解释的官方个人资料统计
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderProfileStatistics {
    pub display_name: Option<String>,
@@ -909,16 +920,16 @@ pub struct ProviderProfileStatistics {
    pub activity_insights: ProviderProfileActivityInsights,
 }

-/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数。
+/// Provider 头像正文的中立字节流；公共层不解释 MIME，也不限制总字节数
 pub type ProviderProfileAvatarStream =
    Pin<Box<dyn Stream<Item = Result<Bytes, ProviderProfileAvatarStreamError>> + Send + 'static>>;

-/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文。
+/// Provider 头像流在响应开始后的通用失败，不携带上游 URL 或正文
 #[derive(Debug, thiserror::Error)]
 #[error("provider profile avatar stream failed")]
 pub struct ProviderProfileAvatarStreamError;

-/// Provider 已校验并打开的官方头像响应。
+/// Provider 已校验并打开的官方头像响应
 pub struct ProviderProfileAvatar {
    pub content_type: Option<String>,
    pub content_length: Option<u64>,
@@ -938,7 +949,7 @@ impl fmt::Debug for ProviderProfileAvatar {
    }
 }

-/// Provider 返回的一张安全主动额度重置卡。
+/// Provider 返回的一张安全主动额度重置卡
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCredit {
    pub id: String,
@@ -948,14 +959,14 @@ pub struct ProviderResetCredit {
    pub reset_type: Option<String>,
 }

-/// Provider 主动额度重置卡列表。
+/// Provider 主动额度重置卡列表
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCredits {
    pub available_count: u64,
    pub credits: Vec<ProviderResetCredit>,
 }

-/// 一次主动额度重置卡消费命令。
+/// 一次主动额度重置卡消费命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ConsumeProviderResetCredit {
    pub account_id: ProviderAccountId,
@@ -963,7 +974,7 @@ pub struct ConsumeProviderResetCredit {
    pub redeem_request_id: Uuid,
 }

-/// Provider 返回的主动额度重置卡消费结果。
+/// Provider 返回的主动额度重置卡消费结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderResetCreditResult {
    pub code: String,
@@ -971,17 +982,18 @@ pub struct ProviderResetCreditResult {
 }

 impl ProviderQuota {
-    /// 保留账号已有的套餐子类型，仅在缺失时使用上游额度快照补全。
+    /// 保留账号已有的套餐子类型，仅在缺失时使用上游额度快照补全
    pub(crate) fn fill_missing_plan_type(&self, account_plan_type: &mut Option<String>) {
        if explicit_plan_type(account_plan_type.as_deref()).is_none() {
            *account_plan_type = explicit_plan_type(self.plan_type.as_deref()).map(str::to_owned);
        }
    }

-    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实。
+    /// 选择账号用量统计的周/月窗口，同时返回展示所需的周期事实
    ///
    /// 只使用边界完整、可归属到整个账号的窗口；周优先于月，同周期保持
-    /// Provider 投影顺序。没有符合条件的窗口时不回退到短期或历史累计。
+    /// Provider 投影顺序
+    /// 没有符合条件的窗口时不回退到短期或历史累计
    #[must_use]
    pub fn usage_window(&self) -> Option<(&ProviderQuotaWindow, AccountUsagePeriod)> {
        self.usage_windows()
@@ -989,7 +1001,7 @@ impl ProviderQuota {
            .min_by_key(|(_, period)| *period)
    }

-    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量。
+    /// 统计与预测共用窗口归属规则，避免把模型专属桶或短期限流当作账号容量
    pub(crate) fn usage_windows(
        &self,
    ) -> impl Iterator<Item = (&ProviderQuotaWindow, AccountUsagePeriod)> {
@@ -1011,11 +1023,12 @@ impl ProviderQuota {
        })
    }

-    /// 返回 Dashboard 使用的代表性额度比例。
+    /// 返回 Dashboard 使用的代表性额度比例
    ///
    /// 优先使用覆盖账号全部请求的窗口；同一归属范围内再依次使用短周期、周、月
-    /// 和其它窗口，同一优先级取较高的已用比例。这里只解释跨 Provider 共享的窗口
-    /// 语义，绝不读取 Provider 私有 JSON。
+    /// 和其它窗口，同一优先级取较高的已用比例
+    /// 这里只解释跨 Provider 共享的窗口
+    /// 语义，绝不读取 Provider 私有 JSON
    #[must_use]
    pub fn representative_used_percent(&self) -> Option<f64> {
        if self.limit_reached {
@@ -1025,7 +1038,7 @@ impl ProviderQuota {
            .map(|(_, used_percent)| used_percent)
    }

-    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义。
+    /// 选择 Dashboard 展示的真实窗口；没有百分比时仍保留 Provider 的滚动窗口语义
    #[must_use]
    pub fn representative_window(&self) -> Option<&ProviderQuotaWindow> {
        self.representative_used_window()
@@ -1039,10 +1052,10 @@ impl ProviderQuota {
            })
    }

-    /// 将已确认的账号级额度耗尽事实投影到展示窗口。
+    /// 将已确认的账号级额度耗尽事实投影到展示窗口
    ///
    /// Provider 已指出具体触顶窗口时只归一化这些窗口；否则归一化 Dashboard
-    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽。
+    /// 同样会选择的代表窗口，避免把多个独立额度窗口全部伪造成已用尽
    pub fn apply_limit_reached_display(&mut self) {
        if !self.limit_reached {
            return;
@@ -1122,21 +1135,21 @@ fn is_week_window(seconds: u64) -> bool {
    seconds > 0 && seconds.abs_diff(WEEK_SECONDS) <= WEEK_SECONDS / 20
 }

-/// Provider 实时模型目录的一项。
+/// Provider 实时模型目录的一项
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModel {
    pub id: UpstreamModelId,
    pub name: String,
 }

-/// Provider 实时模型目录。
+/// Provider 实时模型目录
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModels {
    pub models: Vec<ProviderModel>,
    pub observed_at: Option<DateTime<Utc>>,
 }

-/// Provider 原生模型目录正文；wire 语义由对应 Provider 拥有，公共层只搬运不解释字段。
+/// Provider 原生模型目录正文；wire 语义由对应 Provider 拥有，公共层只搬运不解释字段
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ProviderModelCatalogDocument {
    pub document: RawJsonPayload,
@@ -1144,7 +1157,7 @@ pub struct ProviderModelCatalogDocument {
    pub observed_at: DateTime<Utc>,
 }

-/// 插件账号回调的服务端过滤条件；Provider 缺省时跨全部已注册类型分页。
+/// 插件账号回调的服务端过滤条件；Provider 缺省时跨全部已注册类型分页
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PluginAccountListQuery {
    pub provider_kind: Option<ProviderKind>,
@@ -1158,7 +1171,7 @@ pub struct PluginAccountPage {
    pub next_cursor: Option<ProviderAccountId>,
 }

-/// 原始凭据与当前账号 revision 的同一读取结果。
+/// 原始凭据与当前账号 revision 的同一读取结果
 #[derive(Clone, PartialEq)]
 pub struct PluginAccountCredential {
    pub account: AccountRecord,
@@ -1175,7 +1188,7 @@ impl fmt::Debug for PluginAccountCredential {
    }
 }

-/// Runtime 已完成 wire 校验、Admin 仍需绑定当前账号和 revision 的 prepared facts。
+/// Runtime 已完成 wire 校验、Admin 仍需绑定当前账号和 revision 的 prepared facts
 #[derive(Debug, Clone, PartialEq)]
 pub enum PreparedPluginAccountSave {
    Create(PreparedCredentialCreate),
@@ -1192,20 +1205,20 @@ pub struct PluginAccountSaveResult {
    pub credential_revision: Revision,
 }

-/// Provider 执行 refresh 时所需的当前公共账号事实。
+/// Provider 执行 refresh 时所需的当前公共账号事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PrepareCredentialRefresh {
    pub account: AccountRecord,
 }

-/// Provider 敏感导出结果。
+/// Provider 敏感导出结果
 pub struct ProviderExport {
    pub provider_kind: ProviderKind,
    pub account_ids: Vec<ProviderAccountId>,
    pub document: ProviderDocument,
 }

-/// Store 为 Provider 导出序列化准备的最小输入；material 对公共层保持不透明。
+/// Store 为 Provider 导出序列化准备的最小输入；material 对公共层保持不透明
 #[derive(Debug, Clone, PartialEq)]
 pub struct ProviderExportCredentialInput {
    pub account: AccountRecord,
@@ -1223,19 +1236,20 @@ impl fmt::Debug for ProviderExport {
    }
 }

-/// 统一账号目录的一行完整结果。
+/// 统一账号目录的一行完整结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryItem {
    pub account: AccountRecord,
+    pub capacity: super::accounts::AccountCapacity,
    pub capabilities: super::accounts::ProviderAccountCapabilities,
-    /// Provider 提供的套餐展示名称；未识别到套餐时为空。
+    /// Provider 提供的套餐展示名称；未识别到套餐时为空
    pub plan_type_display: Option<String>,
    pub projection: gateway_core::account::AccountStatusProjection,
    pub usage: Option<super::accounts::AccountUsage>,
    pub quota: ProviderQuota,
 }

-/// 统一账号目录页。
+/// 统一账号目录页
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountDirectoryPage {
    pub config_revision: Revision,
@@ -1244,14 +1258,14 @@ pub struct AccountDirectoryPage {
    pub summary: AccountSummary,
 }

-/// 凭据刷新提交后的完整账号结果。
+/// 凭据刷新提交后的完整账号结果
 #[derive(Debug, Clone, PartialEq)]
 pub struct AccountRefreshResult {
    pub config_revision: Revision,
    pub account: AccountDirectoryItem,
 }

-/// 多 Provider 导出文档集合。
+/// 多 Provider 导出文档集合
 pub struct AccountExportBundle {
    pub exported_at: DateTime<Utc>,
    pub documents: Vec<ProviderExport>,
@@ -1,4 +1,4 @@
-//! 可复用的账号出口配置，以及脱敏后的连通性测试结果。
+//! 可复用的账号出口配置，以及脱敏后的连通性测试结果

 use chrono::{DateTime, Utc};
 use gateway_core::account::{OutboundProxy, RequestLocation};
@@ -39,7 +39,7 @@ pub struct ProxyAccountRef {
    pub enabled: bool,
 }

-/// 按代理查询关联账号，分页与搜索均在存储层执行。
+/// 按代理查询关联账号，分页与搜索均在存储层执行
 #[derive(Debug, Clone)]
 pub struct ProxyAccountListQuery {
    pub proxy_id: String,
@@ -94,7 +94,7 @@ pub struct ProxyPage {
 #[derive(Debug, Clone)]
 pub struct NewProxy {
    pub auto_location: bool,
-    /// 由管理用例探测，随配置原子保存，不接受 HTTP 调用方提供结果。
+    /// 由管理用例探测，随配置原子保存，不接受 HTTP 调用方提供结果
    pub test: Option<ProxyTestResult>,
    pub location: Option<gateway_core::account::RequestLocation>,
    pub name: String,
@@ -105,7 +105,7 @@ pub struct NewProxy {
 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,
@@ -119,7 +119,7 @@ pub struct ProxyMutation {
    pub record: ProxyRecord,
 }

-/// 检测失败与连通性分开，双栈冲突不得继续应用旧位置。
+/// 检测失败与连通性分开，双栈冲突不得继续应用旧位置
 #[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(tag = "status", rename_all = "camelCase")]
 pub enum ProxyLocationDetection {
@@ -155,7 +155,7 @@ impl ProxyRecord {
        }
    }

-    /// 未知出口可暂用上次成功结果，已知出口变化或时区冲突必须撤销旧覆盖。
+    /// 未知出口可暂用上次成功结果，已知出口变化或时区冲突必须撤销旧覆盖
    #[must_use]
    pub fn detected_location_after_test(
        &self,
@@ -1,4 +1,4 @@
-//! 账号额度的只读容量估算，不参与金额结算或账号调度。
+//! 账号额度的只读容量估算，不参与金额结算或账号调度

 use chrono::{DateTime, Duration, Utc};

@@ -28,9 +28,6 @@ pub struct AccountQuotaForecast {
    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)]
@@ -43,9 +40,9 @@ pub struct QuotaForecastSource {
    pub usd: Option<f64>,
 }

-/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口。
+/// 为目标周期选择唯一的预测源窗口；缺少同周期窗口时复用最短的可统计窗口
 ///
-/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口。
+/// Admin 的历史查询与最终投影必须共用这里的顺序，避免查询不会进入响应的窗口
 pub(crate) fn quota_forecast_source_window(
    quota: &ProviderQuota,
    period: AccountUsagePeriod,
@@ -56,8 +53,8 @@ pub(crate) fn quota_forecast_source_window(
        .or_else(|| quota.usage_windows().min_by_key(|(_, period)| *period))
 }

-/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算。
-/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度。
+/// 优先预测真实的对应窗口；缺少对应周期时只给出明确标识的 7/30 天容量折算
+/// 本地日志不能证明站外消耗或完整留存，因此即使样本充足也不声称官方额度
 #[must_use]
 pub fn account_quota_forecasts(
    quota: &ProviderQuota,
@@ -81,8 +78,6 @@ pub fn account_quota_forecasts(
            incomplete_tokens: false,
            estimated_tokens: None,
            estimated_usd: None,
-            remaining_tokens: None,
-            remaining_usd: None,
        };
        if let Some((window, source_period)) = selected {
            forecast.project(
@@ -183,22 +178,21 @@ impl AccountQuotaForecast {
        };
        self.low_sample = sample.sampled_percent < LOW_SAMPLE_PERCENT
            || (method == QuotaForecastMethod::Incremental && sample.block_count < 2);
-        // 漏记和个别缺失只影响精度，仍按已记录数值估算，不按请求数补齐未知消耗。
-        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额。
-        // 已发生的用量保持本周期累计，只把近期消耗比例用于尚未使用的额度。
+        // 漏记和个别缺失只影响精度，仍按已记录数值估算，不按请求数补齐未知消耗
+        // 预测是近似展示值；不复用为账单金额，也不把月折算当成自然月或额外余额
+        // 已发生的用量保持本周期累计，只把近期消耗比例用于尚未使用的额度
        let factor = self.target_seconds as f64 / seconds as f64;
        let remaining_factor = (100.0 - percent) / sample.sampled_percent;
        let remaining_tokens = Some(sample.usage.tokens)
            .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)
+        let 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)
+            .zip(remaining_usd)
            .and_then(|(used, remaining)| estimate(used + remaining, factor));
        self.unavailable_reason = if self.estimated_tokens.is_none() && self.estimated_usd.is_none()
        {
@@ -1,10 +1,10 @@
-//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径。
+//! 预测专用的配对采样；不改变完整交付用量或费用账本的统计口径

 use chrono::{DateTime, Utc};

 use super::provider_credentials::ProviderDocument;

-/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间。
+/// 限制带 Provider 文档的历史点数量；累计用量仍覆盖整个查询区间
 pub const MAX_FORECAST_HISTORY_POINTS: usize = 128;
 const MIN_BLOCK_PERCENT: f64 = 5.0;
 const RECENT_BLOCKS: usize = 3;
@@ -15,7 +15,7 @@ pub struct QuotaForecastUsage {
    pub tokens: u64,
    pub input_tokens: u64,
    pub output_tokens: u64,
-    pub cached_tokens: u64,
+    pub cached_input_tokens: u64,
    pub missing_token_count: u64,
    pub known_cost_count: u64,
    pub unavailable_cost_count: u64,
@@ -24,7 +24,7 @@ pub struct QuotaForecastUsage {
 }

 impl QuotaForecastUsage {
-    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点。
+    /// 累计计数倒退表示不能配对，不用饱和减法掩盖数据断点
    fn difference(&self, baseline: &Self) -> Option<Self> {
        let usd = self.usd - baseline.usd;
        if !usd.is_finite() || usd < -1e-9 {
@@ -35,7 +35,9 @@ impl QuotaForecastUsage {
            tokens: self.tokens.checked_sub(baseline.tokens)?,
            input_tokens: self.input_tokens.checked_sub(baseline.input_tokens)?,
            output_tokens: self.output_tokens.checked_sub(baseline.output_tokens)?,
-            cached_tokens: self.cached_tokens.checked_sub(baseline.cached_tokens)?,
+            cached_input_tokens: self
+                .cached_input_tokens
+                .checked_sub(baseline.cached_input_tokens)?,
            missing_token_count: self
                .missing_token_count
                .checked_sub(baseline.missing_token_count)?,
@@ -68,7 +70,7 @@ pub struct QuotaForecastHistory {
    pub pending_request_count: u64,
 }

-/// 具体 Provider 从自己的历史文档解释出的额度事实。
+/// 具体 Provider 从自己的历史文档解释出的额度事实
 #[derive(Debug, Clone, PartialEq)]
 pub struct QuotaForecastObservation {
    pub used_percent: f64,
@@ -101,13 +103,13 @@ pub struct QuotaForecastSample {
    pub observation_count: usize,
    pub pending_request_count: u64,
    pub discontinuous: bool,
-    /// 本周期已记录用量；近期采样仅用于预测剩余量，不能覆盖这份累计值。
+    /// 本周期已记录用量；近期采样仅用于预测剩余量，不能覆盖这份累计值
    pub cycle_usage: QuotaForecastUsage,
    pub usage: QuotaForecastUsage,
 }

-/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部。
-/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛。
+/// 对同一额度段的累计点形成至少 5 个百分点的连续块，使用最近三个完整块及尾部
+/// 不平均逐请求比值；重复百分比不增加块数，5/10 个百分点仅是量化噪声门槛
 #[must_use]
 pub fn select_forecast_sample(
    key: String,
@@ -139,8 +141,8 @@ pub fn select_forecast_sample(
        usage: current.usage.clone(),
    };
    history.push(current);
-    // 重置边界不在查询起点时，从首个新观测重新计数，避免把旧周期累计带入总量。
-    let mut cycle_baseline = interrupted.then(|| &history[0]);
+    // 重置边界不在查询起点时，从首个新观测重新计数，避免把旧周期累计带入总量
+    let cycle_baseline = interrupted.then(|| &history[0]);
    let mut anchors: Vec<&QuotaForecastPoint> = Vec::new();
    let mut high_water: Option<&QuotaForecastPoint> = None;
    for point in &history {
@@ -149,13 +151,13 @@ pub fn select_forecast_sample(
                continue;
            }
            if point.used_percent < previous.used_percent {
-                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越。
+                // 一个百分点内的回落可能是量化/并发乱序；更大的回落不能跨越
                if previous.used_percent - point.used_percent <= 1.0 {
                    continue;
                }
+                // 同窗口回落不能证明周期重置，只重建采样并保留已记录累计
                sample.discontinuous = true;
                anchors.clear();
-                cycle_baseline = Some(point);
            }
        }
        high_water = Some(point);
@@ -198,7 +200,7 @@ pub fn select_forecast_sample(
    sample.sampled_percent = progress;
    sample.block_count = anchors.len() - baseline_index - 1;
    sample.usage = usage;
-    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算。
+    // 断点后的新基线已有足够进度时，只消费新段；旧段从不参与本次估算
    sample.discontinuous = false;
    sample
 }
@@ -0,0 +1,59 @@
+//! 历史数据保留规则；存储实现只接受已校验的窗口
+
+use super::AdminError;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RetentionTarget {
+    ModelRequests,
+    OpsEvents,
+    AdminAuditEvents,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RetentionPolicy {
+    usage_days: u32,
+    ops_days: u32,
+    audit_days: u32,
+}
+
+impl RetentionPolicy {
+    /// 保留期管理与全量设置保存共用的字段约束
+    pub fn validate_values(
+        usage_days: u32,
+        ops_days: u32,
+        audit_days: u32,
+    ) -> Result<(), &'static str> {
+        for (valid, field) in [
+            (usage_days >= 31, "usage_retention_days"),
+            (ops_days > 0, "ops_event_retention_days"),
+            (audit_days > 0, "audit_retention_days"),
+        ] {
+            if !valid {
+                return Err(field);
+            }
+        }
+        Ok(())
+    }
+
+    pub fn try_new(usage_days: u32, ops_days: u32, audit_days: u32) -> Result<Self, AdminError> {
+        if Self::validate_values(usage_days, ops_days, audit_days).is_err() {
+            return Err(AdminError::invalid(
+                "请求保留期至少 31 天，事件与审计保留期必须为正数",
+            ));
+        }
+        Ok(Self {
+            usage_days,
+            ops_days,
+            audit_days,
+        })
+    }
+
+    #[must_use]
+    pub const fn days(self, target: RetentionTarget) -> u32 {
+        match target {
+            RetentionTarget::ModelRequests => self.usage_days,
+            RetentionTarget::OpsEvents => self.ops_days,
+            RetentionTarget::AdminAuditEvents => self.audit_days,
+        }
+    }
+}
@@ -1,4 +1,4 @@
-//! Runtime settings 与明文管理员 API Key 的语义模型。
+//! Runtime settings 与明文管理员 API Key 的语义模型

 use std::{collections::BTreeMap, fmt};

@@ -8,37 +8,58 @@ use gateway_core::routing::{ProviderKind, PublicModelId, UpstreamModelId};

 use super::Revision;

-/// 客户端模型到上游模型的全局精确映射。
+/// 客户端模型到上游模型的全局精确映射
 pub type ModelMappings = BTreeMap<PublicModelId, UpstreamModelId>;

-/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间。
+/// 全局模型映射的数量与文本约束；调用方保留各自的键值表示
+pub fn validate_model_mappings<'a>(
+    mappings: impl ExactSizeIterator<Item = (&'a str, &'a str)>,
+) -> Result<(), &'static str> {
+    if mappings.len() > 512 {
+        return Err("model_mappings");
+    }
+    for (requested, upstream) in mappings {
+        for value in [requested, upstream] {
+            if value.is_empty()
+                || value.len() > 256
+                || value.bytes().any(|byte| byte.is_ascii_control())
+            {
+                return Err("model_mappings");
+            }
+        }
+    }
+    Ok(())
+}
+
+/// Provider-owned 请求画像选择；Provider ID 是唯一命名空间
 pub type ProviderRequestProfiles =
    BTreeMap<ProviderKind, gateway_core::account::OpaqueProviderData>;

-/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择。
+/// Provider-owned 请求画像的部分更新；`None` 只表示显式删除该 Provider 的历史选择
 pub type ProviderRequestProfileUpdates =
    BTreeMap<ProviderKind, Option<gateway_core::account::OpaqueProviderData>>;

-/// 账号调度策略；由 Core 拥有稳定值与 wire 映射。
+/// 账号调度策略；由 Core 拥有稳定值与 wire 映射
 pub use gateway_core::account::RotationStrategy;

-/// 完整运行设置事实。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct RuntimeSettings {
-    pub request_profiles: ProviderRequestProfiles,
-    pub config_revision: Revision,
+/// 运行设置的共同值；版本、Provider 画像更新和数据库秘密由外层类型拥有
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct RuntimeSettingsValues {
+    pub codex_privacy_policy: gateway_core::settings::privacy::CodexPrivacyPolicy,
    pub request_location_enabled: bool,
    pub request_location: gateway_core::account::RequestLocation,
-    pub 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 openai_guardian_reserved_concurrency: u32,
+    pub openai_account_affinity: gateway_core::account::AccountAffinity,
+    pub max_account_rotations: u32,
+    pub openai_session_affinity_ttl_hours: u32,
    pub responses_max_decompressed_body_bytes: u64,
-    pub rotation_strategy: RotationStrategy,
+    pub smart_scheduling: gateway_core::account::SmartSchedulingConfig,
    pub min_codex_desktop_version: Option<String>,
    pub min_codex_cli_version: Option<String>,
    pub usage_retention_days: u32,
@@ -54,45 +75,38 @@ pub struct RuntimeSettings {
    pub account_warmup_enabled: bool,
    pub account_warmup_schedule_time: String,
    pub account_warmup_model: Option<String>,
+}
+
+/// 完整运行设置事实
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
+pub struct RuntimeSettings {
+    #[serde(flatten)]
+    pub values: RuntimeSettingsValues,
+    pub request_profiles: ProviderRequestProfiles,
+    pub config_revision: Revision,
+    pub model_mappings: ModelMappings,
+    pub rotation_strategy: RotationStrategy,
    pub updated_at: DateTime<Utc>,
 }

-/// 原子替换运行设置的命令。
-#[derive(Debug, Clone, PartialEq, Eq)]
+/// 原子替换运行设置的命令
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
 pub struct ReplaceRuntimeSettings {
-    /// 只覆盖提交的 Provider；未提交项保留当前持久值。
+    #[serde(flatten)]
+    pub values: RuntimeSettingsValues,
+    /// 读取设置时的版本；与写入在同一事务内比较，防止覆盖并发更新
+    pub expected_revision: Revision,
+    /// 只覆盖提交的 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 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)]
+/// 明文管理员 API Key；按产品约束明文落库，但禁止 Debug 泄漏
+#[derive(Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(transparent)]
 pub struct AdminApiKey(String);

 impl AdminApiKey {
@@ -106,7 +120,7 @@ impl AdminApiKey {
        &self.0
    }

-    /// 仅供显式 regenerate 响应读取一次。
+    /// 仅供显式 regenerate 响应读取一次
    #[must_use]
    pub fn expose_for_response(&self) -> &str {
        &self.0
@@ -119,14 +133,17 @@ impl fmt::Debug for AdminApiKey {
    }
 }

-/// 管理员 API Key 更新结果。
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+/// 管理员 API Key 更新结果
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
 pub struct AdminApiKeyMutation {
    pub config_revision: Revision,
    pub exists: bool,
 }

-/// 新管理员 API Key 的一次性返回结果。
+/// 新管理员 API Key 的一次性返回结果
+#[derive(serde::Serialize, serde::Deserialize)]
+#[serde(deny_unknown_fields)]
 pub struct RegeneratedAdminApiKey {
    pub mutation: AdminApiKeyMutation,
    pub key: AdminApiKey,
@@ -152,3 +169,69 @@ impl RuntimeSettings {
            .and_then(|provider| self.request_profiles.get(&provider))
    }
 }
+
+impl From<RuntimeSettings> for ReplaceRuntimeSettings {
+    fn from(settings: RuntimeSettings) -> Self {
+        Self {
+            expected_revision: settings.config_revision,
+            request_profile_updates: settings
+                .request_profiles
+                .into_iter()
+                .map(|(provider, value)| (provider, Some(value)))
+                .collect(),
+            values: settings.values,
+            model_mappings: settings.model_mappings,
+            rotation_strategy: settings.rotation_strategy,
+        }
+    }
+}
+
+impl RuntimeSettingsValues {
+    /// 校验共同事实，返回字段名供边界转换错误；SQL 类型转换仍由 Store 处理
+    pub fn validate(&self) -> Result<(), &'static str> {
+        self.request_location
+            .validate()
+            .map_err(|_| "request_location")?;
+        gateway_core::settings::validate_request_limits(
+            self.max_waiting_per_key,
+            self.max_waiting_per_account,
+            self.concurrency_wait_timeout_seconds,
+            self.max_account_rotations,
+            self.openai_session_affinity_ttl_hours,
+        )?;
+        gateway_core::settings::response_body_limit(self.responses_max_decompressed_body_bytes)?;
+        gateway_core::settings::client_min_versions(
+            self.min_codex_desktop_version.as_deref(),
+            self.min_codex_cli_version.as_deref(),
+        )?;
+        for (valid, field) in [
+            (
+                self.refresh_margin_seconds > 0
+                    && i64::try_from(self.refresh_margin_seconds).is_ok(),
+                "refresh_margin_seconds",
+            ),
+            (self.refresh_concurrency > 0, "refresh_concurrency"),
+        ] {
+            if !valid {
+                return Err(field);
+            }
+        }
+        super::retention::RetentionPolicy::validate_values(
+            self.usage_retention_days,
+            self.ops_event_retention_days,
+            self.audit_retention_days,
+        )?;
+        gateway_core::provider_ports::ProviderFreezePolicy::validate_values(
+            self.account_auto_freeze_threshold,
+            self.account_auto_freeze_window_seconds,
+            self.account_auto_freeze_duration_seconds,
+            self.account_auto_freeze_probe_model.as_deref(),
+        )?;
+        gateway_core::provider_ports::ProviderWarmupPolicy::validate_values(
+            self.account_warmup_enabled,
+            &self.account_warmup_schedule_time,
+            self.account_warmup_model.as_deref(),
+        )?;
+        Ok(())
+    }
+}
@@ -1,9 +1,9 @@
-//! 版本、自更新、回滚与进程重启的 UTC 语义模型。
+//! 版本、自更新、回滚与进程重启的 UTC 语义模型

 use chrono::{DateTime, Utc};
 use serde::{Deserialize, Serialize};

-/// 本次检查或安装选择的更新稳定性范围，具体版本准入由 Host 判定。
+/// 本次检查或安装选择的更新稳定性范围，具体版本准入由 Host 判定
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum SystemUpdateChannel {
@@ -28,7 +28,7 @@ impl SystemUpdateChannel {
    }
 }

-/// Host 返回的本次检查通道及当前构建允许选择的范围。
+/// Host 返回的本次检查通道及当前构建允许选择的范围
 #[derive(Debug, Clone, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SystemUpdatePolicy {
@@ -36,9 +36,9 @@ pub struct SystemUpdatePolicy {
    pub available_channels: Vec<SystemUpdateChannel>,
 }

-/// 当前运行版本及更新检查摘要。
+/// 当前运行版本及更新检查摘要
 ///
-/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成。
+/// `deployment_mode_label` 之类的本地化字符串由 API 根据原始枚举值生成
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemVersion {
    pub version: String,
@@ -52,9 +52,9 @@ pub struct SystemVersion {
    pub update_warning: Option<String>,
 }

-/// 发布源提供的完整更新详情。
+/// 发布源提供的完整更新详情
 ///
-/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实。
+/// 部署模式与构建类型的展示标签归 API；其余字段均为 Host 已确认的原始事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateDetail {
    pub policy: SystemUpdatePolicy,
@@ -71,7 +71,7 @@ pub struct SystemUpdateDetail {
    pub warning: Option<String>,
 }

-/// 系统操作类型。
+/// 系统操作类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemOperationKind {
    Update,
@@ -79,7 +79,7 @@ pub enum SystemOperationKind {
    Restart,
 }

-/// 系统操作状态。
+/// 系统操作状态
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemOperationStatus {
    Idle,
@@ -88,7 +88,7 @@ pub enum SystemOperationStatus {
    Failed,
 }

-/// 持久化系统操作的完整状态。
+/// 持久化系统操作的完整状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemOperationState {
    pub operation_id: Option<String>,
@@ -101,7 +101,7 @@ pub struct SystemOperationState {
    pub finished_at: Option<DateTime<Utc>>,
 }

-/// 最近一次系统操作及版本交换状态。
+/// 最近一次系统操作及版本交换状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateStatus {
    pub previous_version: Option<String>,
@@ -110,7 +110,7 @@ pub struct SystemUpdateStatus {
    pub operation: SystemOperationState,
 }

-/// 自更新日志级别。
+/// 自更新日志级别
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum SystemUpdateEventLevel {
    Info,
@@ -119,7 +119,7 @@ pub enum SystemUpdateEventLevel {
    Error,
 }

-/// 一条已脱敏的系统更新事件。
+/// 一条已脱敏的系统更新事件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SystemUpdateEvent {
    pub id: String,
@@ -132,7 +132,7 @@ pub struct SystemUpdateEvent {
    pub occurred_at: DateTime<Utc>,
 }

-/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态。
+/// 已受理的异步系统操作；不同 wire shape 由枚举保持为合法状态
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum SystemOperationAccepted {
    Update {
@@ -162,3 +162,21 @@ impl SystemOperationAccepted {
        }
    }
 }
+
+/// 重启前的只读确认快照；目标发行与全局配置版本一起绑定用户确认
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SystemRestartPlan {
+    pub target_version: Option<String>,
+    pub release_manifest_sha256: Option<String>,
+    pub config_revision: u64,
+    pub incompatible_plugins: Vec<SystemIncompatiblePlugin>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase", deny_unknown_fields)]
+pub struct SystemIncompatiblePlugin {
+    pub instance_id: String,
+    pub name: String,
+    pub reason: String,
+}
@@ -1,9 +1,10 @@
-//! 备份控制面所需的持久化与基础设施能力。
+//! 备份控制面所需的持久化与基础设施能力
 //!
 //! 端口方法只接受/返回领域类型与既有错误体系：`BackupRepository` 复用
 //! `AdminStoreError`；`DatabaseDumpPort` 与 `BackupObjectStorePort` 返回只携带稳定
-//! 错误码的 [`BackupError`]。`gateway-store` 实现全部端口；`gateway-admin` 拥有
-//! 状态机、Cron、保留策略与 BackupTask 算法。
+//! 错误码的 [`BackupError`]
+//! `gateway-store` 实现全部端口；`gateway-admin` 拥有
+//! 状态机、Cron、保留策略与 BackupTask 算法

 use std::path::PathBuf;
 use std::sync::Arc;
@@ -17,13 +18,13 @@ use crate::model::{
    MutationContext,
    backup::{
        BackupError, BackupObjectMetadata, BackupRecord, BackupRecordListQuery, BackupRecordPage,
-        BackupRecordSeed, BackupSettings, BackupStatus, BackupStorageConfig, ConnectionTestResult,
-        UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
+        BackupRecordSeed, BackupSettings, BackupStatusTransition, BackupStorageConfig,
+        ConnectionTestResult, UpdateBackupScheduleCommand, UpdateBackupStorageCommand,
    },
 };
 use crate::ports::store::AdminStoreResult;

-/// Worker 状态迁移携带的字段更新；`None` 字段不写入。
+/// Worker 状态迁移携带的字段更新；`None` 字段不写入
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct StatusTransitionUpdate {
    pub size_bytes: Option<u64>,
@@ -33,122 +34,133 @@ pub struct StatusTransitionUpdate {
    pub completed_at: Option<DateTime<Utc>>,
 }

-/// 备份配置、任务与计划游标的 PostgreSQL 仓储端口。
+/// 备份配置、任务与计划游标的 PostgreSQL 仓储端口
 #[async_trait]
 pub trait BackupRepository: Send + Sync {
-    /// 读取完整设置（含 Secret）。
+    /// 读取完整设置（含 Secret）
    async fn load_settings(&self) -> AdminStoreResult<BackupSettings>;

-    /// 同事务更新 S3 存储配置、递增 revision、清空验证状态并写审计事件。
+    /// 同事务更新 S3 存储配置、递增 revision、清空验证状态并写审计事件
    ///
-    /// 已有记录时禁止切换 endpoint/region/bucket/path-style（存储身份锁定）。
-    /// 返回更新后的设置与新的全局 `config_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,
+        timezone: gateway_core::time::DeploymentTimeZone,
    ) -> AdminStoreResult<BackupSettings>;

-    /// CAS 记录探针成功；`storage_revision` 与当前配置不一致时丢弃结果（返回 `false`）。
+    /// CAS 记录探针成功；`storage_revision` 与当前配置不一致时丢弃结果（返回 `false`）
    async fn record_verification(
        &self,
        storage_revision: u64,
        at: DateTime<Utc>,
    ) -> AdminStoreResult<bool>;

-    /// 插入 queued 任务；存在活跃任务时返回 `backup.active_task_conflict`。
+    /// 插入 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>;
+    /// 核对启停、Cron、时区及旧游标后，同事务推进游标并插入 scheduled 任务
+    /// 配置已变化时不写入；同一时间点或活跃冲突时只推进游标，返回 `false`
+    async fn insert_scheduled_record(
+        &self,
+        seed: BackupRecordSeed,
+        next_run_at: Option<DateTime<Utc>>,
+        expected_cron: &str,
+        expected_timezone: &str,
+        expected_next_run_at: Option<DateTime<Utc>>,
+    ) -> 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），供启动恢复。
+    /// 读取中间状态记录（dumping/uploading），供启动恢复
    async fn list_intermediate_records(&self) -> AdminStoreResult<Vec<BackupRecord>>;

-    /// 读取等待完成墓碑的记录（status = deleting）。
+    /// 读取等待完成墓碑的记录（status = deleting）
    async fn list_pending_deletions(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;

-    /// 读取 `expires_at` 已到期且非活跃的记录（completed/failed），供保留清理。
+    /// 读取 `expires_at` 已到期且非活跃的记录（completed/failed），供保留清理
    async fn list_expired_records(&self, limit: u32) -> AdminStoreResult<Vec<BackupRecord>>;

-    /// 原子领取最旧的 queued 任务并迁移到 dumping；无任务返回 `None`。
+    /// 原子领取最旧的 queued 任务并迁移到 dumping；无任务返回 `None`
    async fn claim_next_queued(&self, now: DateTime<Utc>)
    -> AdminStoreResult<Option<BackupRecord>>;

-    /// 条件迁移状态：要求当前状态一致；不匹配返回 `None`。
+    /// 条件迁移状态：要求当前状态一致；不匹配返回 `None`
    async fn transition_status(
        &self,
        id: &str,
-        from: BackupStatus,
-        to: BackupStatus,
+        transition: BackupStatusTransition,
        update: StatusTransitionUpdate,
        now: DateTime<Utc>,
    ) -> AdminStoreResult<Option<BackupRecord>>;

-    /// 迁移到删除流程（completed/failed → deleting）；供管理员与保留策略调用。
+    /// 迁移到删除流程（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,
+        expected_timezone: Option<&str>,
+        expected_next_run_at: Option<DateTime<Utc>>,
+        timezone: &str,
    ) -> AdminStoreResult<bool>;

-    /// 按完成时间倒序读取 completed 计划备份，供保留策略扫描（最多 `limit` 条）。
+    /// 按完成时间倒序读取 completed 计划备份，供保留策略扫描（最多 `limit` 条）
    async fn list_scheduled_completed_desc(
        &self,
        limit: u32,
    ) -> AdminStoreResult<Vec<BackupRecord>>;
 }

-/// `pg_dump` 导出与本地暂存端口。
+/// `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` 请求。
+/// 一次 `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,
@@ -156,7 +168,7 @@ pub struct DumpArtifact {
    pub sha256: String,
 }

-/// 暂存目录中已存在的完整归档。
+/// 暂存目录中已存在的完整归档
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct StagedArtifact {
    pub path: PathBuf,
@@ -164,39 +176,39 @@ pub struct StagedArtifact {
    pub sha256: String,
 }

-/// S3 兼容对象存储适配器端口。
+/// S3 兼容对象存储适配器端口
 ///
-/// 方法接受已经校验的存储配置；SDK client 的构造与缓存属于 adapter 实现细节。
+/// 方法接受已经校验的存储配置；SDK client 的构造与缓存属于 adapter 实现细节
 #[async_trait]
 pub trait BackupObjectStorePort: Send + Sync {
-    /// 对专用探针对象执行 Put/Head/Get/Delete。
+    /// 对专用探针对象执行 Put/Head/Get/Delete
    async fn test_connection(
        &self,
        config: &BackupStorageConfig,
    ) -> Result<ConnectionTestResult, BackupError>;

-    /// 分片流式上传本地归档；取消时中止 multipart 并返回 `backup.cancelled`。
+    /// 分片流式上传本地归档；取消时中止 multipart 并返回 `backup.cancelled`
    async fn upload_file(
        &self,
        config: &BackupStorageConfig,
        request: UploadObjectRequest,
    ) -> Result<(), BackupError>;

-    /// 读取对象大小与 metadata；对象不存在返回 `Ok(None)`。
+    /// 读取对象大小与 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。
+    /// 创建短时预签名下载 URL
    async fn presigned_download(
        &self,
        config: &BackupStorageConfig,
@@ -206,7 +218,7 @@ pub trait BackupObjectStorePort: Send + Sync {
    ) -> Result<String, BackupError>;
 }

-/// 一次对象上传请求。
+/// 一次对象上传请求
 #[derive(Debug, Clone)]
 pub struct UploadObjectRequest {
    pub object_key: String,
@@ -215,7 +227,7 @@ pub struct UploadObjectRequest {
    pub cancellation: gateway_core::lifecycle::CancellationToken,
 }

-/// 备份控制面所需的全部 Store 能力集合。
+/// 备份控制面所需的全部 Store 能力集合
 #[derive(Clone)]
 pub struct BackupStorePorts {
    repository: Arc<dyn BackupRepository>,
@@ -224,7 +236,7 @@ pub struct BackupStorePorts {
 }

 impl BackupStorePorts {
-    /// 组合备份端口。
+    /// 组合备份端口
    #[must_use]
    pub fn new(
        repository: Arc<dyn BackupRepository>,
@@ -238,25 +250,25 @@ impl BackupStorePorts {
        }
    }

-    /// 备份任务/配置仓储。
+    /// 备份任务/配置仓储
    #[must_use]
    pub fn repository(&self) -> Arc<dyn BackupRepository> {
        self.repository.clone()
    }

-    /// `pg_dump` 导出与暂存。
+    /// `pg_dump` 导出与暂存
    #[must_use]
    pub fn dump(&self) -> Arc<dyn DatabaseDumpPort> {
        self.dump.clone()
    }

-    /// S3/R2 对象存储适配器。
+    /// S3/R2 对象存储适配器
    #[must_use]
    pub fn object_store(&self) -> Arc<dyn BackupObjectStorePort> {
        self.object_store.clone()
    }

-    /// 测试与不可用路径使用的空实现；任何调用都返回不可用错误。
+    /// 测试与不可用路径使用的空实现；任何调用都返回不可用错误
    #[doc(hidden)]
    #[must_use]
    pub fn disabled() -> Self {
@@ -287,6 +299,7 @@ impl BackupRepository for UnavailableBackupRepository {
        _command: UpdateBackupScheduleCommand,
        _next_run_at: Option<DateTime<Utc>>,
        _context: &MutationContext,
+        _timezone: gateway_core::time::DeploymentTimeZone,
    ) -> AdminStoreResult<BackupSettings> {
        Err(disabled_store())
    }
@@ -303,7 +316,14 @@ impl BackupRepository for UnavailableBackupRepository {
    ) -> AdminStoreResult<BackupRecord> {
        Err(disabled_store())
    }
-    async fn insert_scheduled_record(&self, _seed: BackupRecordSeed) -> AdminStoreResult<bool> {
+    async fn insert_scheduled_record(
+        &self,
+        _seed: BackupRecordSeed,
+        _next_run_at: Option<DateTime<Utc>>,
+        _expected_cron: &str,
+        _expected_timezone: &str,
+        _expected_next_run_at: Option<DateTime<Utc>>,
+    ) -> AdminStoreResult<bool> {
        Err(disabled_store())
    }
    async fn list_backup_records(
@@ -333,8 +353,7 @@ impl BackupRepository for UnavailableBackupRepository {
    async fn transition_status(
        &self,
        _id: &str,
-        _from: BackupStatus,
-        _to: BackupStatus,
+        _transition: BackupStatusTransition,
        _update: StatusTransitionUpdate,
        _now: DateTime<Utc>,
    ) -> AdminStoreResult<Option<BackupRecord>> {
@@ -354,7 +373,9 @@ impl BackupRepository for UnavailableBackupRepository {
        &self,
        _next_run_at: DateTime<Utc>,
        _expected_cron: &str,
-        _expected_timezone: &str,
+        _expected_timezone: Option<&str>,
+        _expected_next_run_at: Option<DateTime<Utc>>,
+        _timezone: &str,
    ) -> AdminStoreResult<bool> {
        Err(disabled_store())
    }
@@ -1,4 +1,4 @@
-//! 客户端安装包解析的外部能力端口。
+//! 客户端安装包解析的外部能力端口

 use async_trait::async_trait;

@@ -1,4 +1,4 @@
-//! 管理用例依赖的外部能力端口。
+//! 管理用例依赖的外部能力端口

 pub mod backup;
 pub mod client_distribution;
@@ -6,9 +6,11 @@ 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 retention;
 pub mod store;
 pub mod system;
@@ -1,4 +1,4 @@
-//! 插件宿主访问账号权威所需的窄端口。
+//! 插件宿主访问账号权威所需的窄端口

 use async_trait::async_trait;
 use gateway_core::account::ProviderAccountId;
@@ -11,7 +11,7 @@ use crate::model::{
    },
 };

-/// Runtime 只取得账号读写用例，不接触 Store、SQL 或完整管理服务集合。
+/// Runtime 只取得账号读写用例，不接触 Store、SQL 或完整管理服务集合
 #[async_trait]
 pub trait PluginAccountAccess: Send + Sync {
    async fn list(&self, query: PluginAccountListQuery) -> Result<PluginAccountPage, AdminError>;
@@ -26,7 +26,7 @@ pub trait PluginAccountAccess: Send + Sync {
        account_id: &ProviderAccountId,
    ) -> Result<PluginAccountCredential, AdminError>;

-    /// 只读 Provider 已有额度观测；实现不得主动刷新上游或附加用量预测。
+    /// 只读 Provider 已有额度观测；实现不得主动刷新上游或附加用量预测
    async fn get_quota(
        &self,
        _account_id: &ProviderAccountId,
@@ -34,6 +34,14 @@ pub trait PluginAccountAccess: Send + Sync {
        Err(AdminError::unavailable("插件额度事实查询暂不可用"))
    }

+    /// 通过 Provider 原生管理路径刷新额度；不向插件暴露凭据或执行额度重置
+    async fn refresh_quota(
+        &self,
+        _account_id: &ProviderAccountId,
+    ) -> Result<crate::model::provider_credentials::ProviderQuota, AdminError> {
+        Err(AdminError::unavailable("插件额度观测刷新暂不可用"))
+    }
+
    async fn save(
        &self,
        command: PreparedPluginAccountSave,
@@ -1,14 +1,35 @@
-//! 插件发现 Client Key 公开身份的窄端口。
+//! 插件 Client Key 非秘密目录与受控预算管理端口

 use async_trait::async_trait;
+use gateway_core::{engine::budget::ClientBudgetStatus, policy::ClientApiKeyId};

 use crate::model::{
-    AdminError,
-    plugin_client_keys::{PluginClientKeyListQuery, PluginClientKeyPage},
+    AdminError, MutationContext,
+    client_keys::{ResetClientKeyBudget, UpdateClientKeyBudgetLimits},
+    plugin_client_keys::{PluginClientKeyFacts, PluginClientKeyListQuery, PluginClientKeyPage},
+    plugin_resources::PluginResourceOwner,
 };

 #[async_trait]
 pub trait PluginClientKeyAccess: Send + Sync {
+    async fn facts(&self, id: &ClientApiKeyId) -> Result<PluginClientKeyFacts, AdminError>;
+
+    async fn budget(&self, id: &ClientApiKeyId) -> Result<ClientBudgetStatus, AdminError>;
+
+    async fn update_budget_limits(
+        &self,
+        owner: &PluginResourceOwner,
+        command: UpdateClientKeyBudgetLimits,
+        context: &MutationContext,
+    ) -> Result<ClientApiKeyId, AdminError>;
+
+    async fn reset_budget(
+        &self,
+        owner: &PluginResourceOwner,
+        command: ResetClientKeyBudget,
+        context: &MutationContext,
+    ) -> Result<ClientApiKeyId, AdminError>;
+
    async fn list(
        &self,
        query: PluginClientKeyListQuery,
@@ -1,5 +1,7 @@
+//! 插件管理页面、资源访问与授权回调的运行时端口
+
 use async_trait::async_trait;
-use gateway_core::runtime::extensions::ExtensionSetReference;
+use gateway_core::routing::extensions::ExtensionSetReference;

 use crate::model::{
    AdminError,
@@ -9,11 +11,11 @@ use crate::model::{
    },
 };

-/// 仅按 Admin 固定的发布引用分派；Runtime 不自行选择当前代次，也不拥有管理员身份。
+/// 仅按 Admin 固定的发布引用分派；Runtime 不自行选择当前代次，也不拥有管理员身份
 #[async_trait]
 pub trait PluginManagement: Send + Sync {
-    /// 复核固定发布代次中的模型访问域；调用方已校验持久实例仍为当前目标。
-    async fn authorize_models(
+    /// 复核固定发布代次中的可用目标；调用方已校验持久实例仍为当前版本
+    async fn validate_target(
        &self,
        published: &ExtensionSetReference,
        target: &PluginManagementTarget,
@@ -1,3 +1,5 @@
+//! 官方插件发行清单与制品文件的读取端口
+
 use std::sync::Arc;

 use async_trait::async_trait;
@@ -9,7 +11,7 @@ pub enum OfficialPluginReleaseReadErrorKind {
    Unavailable,
 }

-/// 文件系统错误不携带部署路径，避免把宿主布局传播到管理域和日志之外。
+/// 文件系统错误不携带部署路径，避免把宿主布局传播到管理域和日志之外
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 #[error("official plugin release files are unavailable")]
 pub struct OfficialPluginReleaseReadError {
@@ -28,7 +30,7 @@ impl OfficialPluginReleaseReadError {
    }
 }

-/// Host 只暴露与宿主发行物同信任边界的只读文件，不解释官方身份或插件包。
+/// Host 只暴露与宿主发行物同信任边界的只读文件，不解释官方身份或插件包
 #[async_trait]
 pub trait OfficialPluginReleaseFiles: Send + Sync {
    async fn manifest(&self) -> Result<Option<Arc<[u8]>>, OfficialPluginReleaseReadError>;
@@ -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>>;
+}
@@ -1,3 +1,5 @@
+//! 插件准备、分发、持久化与私有状态生命周期的外部能力端口
+
 use std::{collections::BTreeMap, sync::Arc};

 use async_trait::async_trait;
@@ -24,12 +26,12 @@ use crate::model::{
        PluginCompatibilityRequirements, PluginSource,
    },
 };
-use gateway_core::runtime::extensions::ExtensionSetReference;
+use gateway_core::routing::extensions::ExtensionSetReference;

-/// Admin 准备完整候选并保活到提交后的发布结束；进程状态不能代替持久启用状态。
+/// Admin 准备完整候选并保活到提交后的发布结束；进程状态不能代替持久启用状态
 #[async_trait]
-pub trait PluginPreparation: Send + Sync {
-    /// 静态判断业务配置是否完整，不启动进程；不完整的安装保留为待配置。
+pub trait PluginPreparation: PluginRuntimeDiagnostics + PluginStateLifecycle {
+    /// 静态判断业务配置是否完整，不启动进程；不完整的安装保留为待配置
    async fn configuration_ready(
        &self,
        instance: PluginInstance,
@@ -39,41 +41,38 @@ pub trait PluginPreparation: Send + Sync {
        &self,
        instance: PluginInstance,
    ) -> Result<PluginStateConfiguration, AdminError>;
-    /// 本次修改的实例 revision 必须等于候选 config_revision，准备失败时拒绝提交；历史故障可隔离。
+    /// 本次修改的实例 revision 必须等于候选 config_revision，准备失败时拒绝提交；历史故障可隔离
    async fn prepare(
        &self,
        snapshot: PluginInstanceSnapshot,
    ) -> Result<ExtensionSetReference, AdminError>;
-    /// 返回当前进程的只读运行事实；缺省实现让不托管插件进程的组合保持兼容。
+}
+
+/// 运行诊断独立于发布准备；没有进程事实时显式返回 None
+#[async_trait]
+pub trait PluginRuntimeDiagnostics: Send + Sync {
    async fn runtime_diagnostics(
        &self,
-        _snapshot: &PluginInstanceSnapshot,
-        _published_revision: Option<u64>,
-        _published: Option<&ExtensionSetReference>,
-    ) -> Option<BTreeMap<String, PluginInstanceRuntime>> {
-        None
-    }
+        snapshot: &PluginInstanceSnapshot,
+        published_revision: Option<u64>,
+        published: Option<&ExtensionSetReference>,
+    ) -> Option<BTreeMap<String, PluginInstanceRuntime>>;
+}
+
+/// 发布实现必须显式承担状态激活、排空和迁移，不能以缺省成功跳过生命周期
+#[async_trait]
+pub trait PluginStateLifecycle: Send + Sync {
    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,
-    ) {
-    }
+        prepared: &ExtensionSetReference,
+        instance: &PluginInstance,
+    ) -> Result<(), AdminError>;
+    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("插件状态迁移运行时不可用"))
-    }
+        prepared: &ExtensionSetReference,
+        transition: PluginStateTransition,
+    ) -> Result<(), AdminError>;
 }

 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
@@ -106,7 +105,7 @@ impl PluginStateStoreError {

 pub type PluginStateStoreResult<T> = Result<T, PluginStateStoreError>;

-/// 私有状态的窄端口；不暴露 SQL、连接或跨命名空间事务。
+/// 私有状态的窄端口；不暴露 SQL、连接或跨命名空间事务
 #[async_trait]
 pub trait PluginStateStore: Send + Sync {
    async fn load_owner(
@@ -154,7 +153,7 @@ pub trait PluginStateStore: Send + Sync {
    async fn abort_transition(&self, transition_id: &str) -> PluginStateStoreResult<()>;
 }

-/// Host 拥有联网、重定向、凭据作用域、限流与有界下载，不解释插件包。
+/// Host 拥有联网、重定向、凭据作用域、限流与有界下载，不解释插件包
 #[async_trait]
 pub trait PluginDistribution: Send + Sync {
    fn validate_source(&self, source: &PluginUpdateSource) -> Result<(), AdminError>;
@@ -173,24 +172,25 @@ pub trait PluginDistribution: Send + Sync {
    ) -> Result<DownloadedPlugin, AdminError>;
 }

-/// Runtime 只解释插件包格式；安装事务与来源选择归 Admin。
+/// Runtime 只解释插件包格式；安装事务与来源选择归 Admin
 #[async_trait]
 pub trait PluginPackageInspector: Send + Sync {
-    /// 当前宿主对权限标识的说明，供展示投影使用，不属于不可变制品元数据。
-    fn permission_descriptions(
+    /// 完整校验包并返回版本范围诊断；校验失败与可加载但未经宿主承诺的提醒分开
+    async fn compatibility_warning(
        &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()
+        archive: Arc<[u8]>,
+        expected_sha256: String,
+    ) -> Result<Option<String>, AdminError> {
+        self.inspect(archive, Some(expected_sha256)).await?;
+        Ok(None)
+    }
+
+    /// 按当前宿主的弃用计划提示旧接口，不改变安装和运行资格
+    fn api_deprecations(
+        &self,
+        _metadata: &crate::model::plugins::PluginArtifactMetadata,
+    ) -> Result<Vec<crate::model::plugins::instances::PluginApiDeprecation>, AdminError> {
+        Ok(Vec::new())
    }

    async fn inspect(
@@ -199,7 +199,7 @@ pub trait PluginPackageInspector: Send + Sync {
        expected_sha256: Option<String>,
    ) -> Result<InspectedPluginArtifact, AdminError>;

-    /// 从已安装且摘要匹配的制品中读取可展示的静态图标，不启动插件实例。
+    /// 从已安装且摘要匹配的制品中读取可展示的静态图标，不启动插件实例
    async fn icon(
        &self,
        _archive: Arc<[u8]>,
@@ -209,7 +209,7 @@ pub trait PluginPackageInspector: Send + Sync {
        Err(AdminError::unavailable("插件图标读取不可用"))
    }

-    /// 只读取已校验包的静态宿主要求；不得准备或启动插件进程。
+    /// 只读取已校验包的静态宿主要求；不得准备或启动插件进程
    async fn compatibility(
        &self,
        _archive: Arc<[u8]>,
@@ -221,13 +221,13 @@ pub trait PluginPackageInspector: Send + Sync {

 #[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,
@@ -235,10 +235,23 @@ pub trait PluginStore: Send + Sync {
    ) -> AdminStoreResult<Option<PluginVersionConfiguration>> {
        Ok(None)
    }
-    /// 只返回有可恢复配置的制品摘要，不读取敏感值。
+    /// 只返回有可恢复配置的制品摘要，不读取敏感值
    async fn configuration_versions(&self, _id: &str) -> AdminStoreResult<Vec<String>> {
        Ok(Vec::new())
    }
+    /// 在单个事务中停用确认快照中的实例，保留配置、密钥及私有状态
+    async fn disable_instances(
+        &self,
+        _ids: &[String],
+        _expected_revision: Revision,
+        _context: &MutationContext,
+    ) -> AdminStoreResult<Revision> {
+        Err(super::store::AdminStoreError::new(
+            super::store::AdminStoreErrorKind::Unavailable,
+            "plugin",
+            "atomic plugin disable is unavailable",
+        ))
+    }
    async fn save_instance(
        &self,
        instance: PluginInstance,
@@ -262,7 +275,7 @@ pub trait PluginStore: Send + Sync {
        self.save_instance(instance, expected_revision, context)
            .await
    }
-    /// 保存目标并停用明确确认的配置，必须共享事务和配置版本检查。
+    /// 保存目标并停用明确确认的配置，必须共享事务和配置版本检查
    async fn save_instance_replacing(
        &self,
        instance: PluginInstance,
@@ -314,13 +327,13 @@ pub trait PluginStore: Send + Sync {
        source: PluginSource,
        context: &MutationContext,
    ) -> AdminStoreResult<PluginArtifactMutation>;
-    /// 接受不可变制品声明的全部能力域；接受事实不随实例设置变化。
+    /// 确认信任并安装精确摘要的制品；安装事实不随实例设置变化
    async fn accept_artifact(
        &self,
        digest: &str,
        context: &MutationContext,
    ) -> AdminStoreResult<PluginArtifactMutation>;
-    /// 删除制品及其无引用下载凭据，最后一个版本同时删除来源规则，清理与审计必须原子提交。
+    /// 删除制品及其无引用下载凭据，最后一个版本同时删除来源规则，清理与审计必须原子提交
    async fn delete_artifact(
        &self,
        digest: &str,
@@ -1,4 +1,4 @@
-//! 手动同步的外部价目来源；网络和外部文档解析由 Host 实现。
+//! 手动同步的外部价目来源；网络和外部文档解析由 Host 实现

 use crate::model::{AdminError, pricing::PricingSyncPreview};
 use async_trait::async_trait;
@@ -1,4 +1,4 @@
-//! 原生 Provider 管理能力与启动时注册表。
+//! 原生 Provider 管理能力与启动时注册表

 use std::{collections::BTreeMap, sync::Arc};

@@ -26,14 +26,14 @@ use crate::model::{
    quota_forecast_sampling::QuotaForecastObservation,
 };

-/// Provider 管理失败的稳定分类。
+/// Provider 管理失败的稳定分类
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ProviderAdminErrorKind {
    Invalid,
    Unsupported,
    NotFound,
    Conflict,
-    /// Provider 已发起不可逆操作，但无法确认最终执行结果。
+    /// Provider 已发起不可逆操作，但无法确认最终执行结果
    Ambiguous,
    Unavailable,
    CredentialRefreshRequired,
@@ -41,16 +41,17 @@ pub enum ProviderAdminErrorKind {
    Internal,
 }

-/// 不携带 OAuth 请求材料的管理错误。
+/// 不携带 OAuth 请求材料的管理错误
 ///
-/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案。
-/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在。
-/// `public_message` 则是明确标记为可公开的静态提示，不允许携带动态上游材料。
-#[derive(Clone, PartialEq, Eq, thiserror::Error)]
+/// `message` 是 Provider 局部诊断，可能包含原始上游正文；通用管理用例不得自动把它作为公开文案
+/// 只有明确拥有原始诊断合同的调用方才能读取，`Debug` 始终只记录是否存在
+/// `public_message` 则是明确标记为可公开的静态提示，不允许携带动态上游材料
+#[derive(Clone, thiserror::Error)]
 #[error("provider admin operation failed: {kind:?}")]
 pub struct ProviderAdminError {
    kind: ProviderAdminErrorKind,
-    message: Option<String>,
+    #[source]
+    diagnostic: Option<Arc<ProviderAdminDiagnostic>>,
    public_message: Option<&'static str>,
 }

@@ -59,7 +60,7 @@ impl std::fmt::Debug for ProviderAdminError {
        formatter
            .debug_struct("ProviderAdminError")
            .field("kind", &self.kind)
-            .field("message", &self.message.as_ref().map(|_| "<redacted>"))
+            .field("message", &self.message().map(|_| "<redacted>"))
            .field("public_message", &self.public_message)
            .finish()
    }
@@ -70,18 +71,26 @@ impl ProviderAdminError {
    pub const fn new(kind: ProviderAdminErrorKind) -> Self {
        Self {
            kind,
-            message: None,
+            diagnostic: None,
            public_message: None,
        }
    }

    #[must_use]
-    pub fn with_message(mut self, message: impl Into<String>) -> Self {
-        self.message = Some(message.into());
+    pub fn with_source(mut self, source: impl Into<gateway_core::error::ErrorSource>) -> Self {
+        Arc::make_mut(self.diagnostic.get_or_insert_with(Default::default)).source =
+            Some(source.into());
        self
    }

-    /// Provider 明确允许公开的静态提示；不得承载上游响应或凭据材料。
+    #[must_use]
+    pub fn with_message(mut self, message: impl Into<String>) -> Self {
+        Arc::make_mut(self.diagnostic.get_or_insert_with(Default::default)).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);
@@ -100,24 +109,61 @@ impl ProviderAdminError {

    #[must_use]
    pub fn message(&self) -> Option<&str> {
-        self.message.as_deref()
+        self.diagnostic
+            .as_ref()
+            .and_then(|diagnostic| diagnostic.message.as_deref())
    }
 }

-/// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力。
+// Provider 局部消息与 typed 来源共用一个不公开的上下文，避免跨用例转换后丢失
+#[derive(Debug, Clone, Default, thiserror::Error)]
+#[error("{}", message.as_deref().unwrap_or("provider admin dependency failed"))]
+struct ProviderAdminDiagnostic {
+    message: Option<String>,
+    source: Option<gateway_core::error::ErrorSource>,
+}
+
+/// 一个具体 Provider 对管理控制面提供的解析、验证、上游交互与运行时资源回收能力
 ///
 /// 数据变更由 Provider 返回 prepared facts；config revision、审计与 PostgreSQL 事务
-/// 全部由 [`crate::ports::store::AccountStore`] 提交。运行时资源通知只在事务成功后发生。
+/// 全部由 [`crate::ports::store::AccountStore`] 提交
+/// 运行时资源通知只在事务成功后发生
 #[async_trait]
 pub trait ProviderAdmin: Send + Sync {
-    /// 只读内置价目；没有本地计价能力的 Provider 返回空目录。
+    fn compile_privacy_policy(
+        &self,
+        _policy: &gateway_core::settings::privacy::CodexPrivacyPolicy,
+    ) -> Result<
+        Arc<dyn gateway_core::settings::privacy::CompiledPrivacyPolicy>,
+        gateway_core::settings::privacy::PrivacyError,
+    > {
+        Err(gateway_core::settings::privacy::PrivacyError {
+            rule_index: 0,
+            reason: "Provider 不支持隐私策略",
+        })
+    }
+
+    fn preview_privacy_policy(
+        &self,
+        _request: gateway_core::settings::privacy::PrivacyPreviewRequest,
+    ) -> Result<
+        gateway_core::settings::privacy::PrivacyPreviewResult,
+        gateway_core::settings::privacy::PrivacyError,
+    > {
+        Err(gateway_core::settings::privacy::PrivacyError {
+            rule_index: 0,
+            reason: "Provider 不支持隐私策略",
+        })
+    }
+
+    /// 只读内置价目；没有本地计价能力的 Provider 返回空目录
    fn pricing_catalog(&self) -> crate::model::pricing::ProviderPricingCatalog {
        Default::default()
    }

    fn provider_kind(&self) -> &ProviderKind;

-    /// 只读取原生 Provider 能力及账号类型，不执行网络或数据库查询。
+    /// 只读取原生 Provider 能力及账号类型，不执行网络或数据库查询
    fn account_capabilities(
        &self,
        _account_id: &ProviderAccountId,
@@ -126,19 +172,19 @@ pub trait ProviderAdmin: Send + Sync {
        Default::default()
    }

-    /// 提供该 Provider 的可选客户端身份；通用管理层不解释内部字段。
+    /// 提供该 Provider 的可选客户端身份；通用管理层不解释内部字段
    fn client_profile_options(
        &self,
    ) -> Result<gateway_core::account::OpaqueProviderData, ProviderAdminError> {
        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 没有持久选择时使用的 Provider 默认画像；只返回已准备的本地事实。
+    /// 没有持久选择时使用的 Provider 默认画像；只返回已准备的本地事实
    fn default_client_profile(&self) -> Option<gateway_core::account::OpaqueProviderData> {
        None
    }

-    /// 校验并投影客户端身份，结果不含认证或账号材料。
+    /// 校验并投影客户端身份，结果不含认证或账号材料
    fn preview_client_profile(
        &self,
        _configuration: &gateway_core::account::OpaqueProviderData,
@@ -146,31 +192,33 @@ pub trait ProviderAdmin: Send + Sync {
        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 将原始套餐值投影为展示名称；默认保留未知 Provider 的原始名称。
+    /// 提供最终套餐展示名称；未覆盖时采用通用的大驼峰格式
    fn plan_type_display(&self, plan_type: &str) -> String {
-        plan_type.to_owned()
+        default_plan_type_display(plan_type)
    }

-    /// 账号已经由控制面提交为不可调度状态，释放 Provider 持有的账号级运行时资源。
+    /// 账号已经由控制面提交为不可调度状态，释放 Provider 持有的账号级运行时资源
    ///
-    /// 无账号级运行时资源的 Provider 不需要执行额外操作。该通知发生在 Store 事务
-    /// 成功之后，不参与事务成败，也不得恢复或改写已经提交的账号状态。
+    /// 无账号级运行时资源的 Provider 不需要执行额外操作
+    /// 该通知发生在 Store 事务
+    /// 成功之后，不参与事务成败，也不得恢复或改写已经提交的账号状态
    async fn account_unavailable(&self, account_id: &ProviderAccountId);

-    /// 账号资格事实已经由控制面提交，失效 Provider 持有的可重建派生状态。
+    /// 账号资格事实已经由控制面提交，失效 Provider 持有的可重建派生状态
    ///
    /// 该通知发生在 Store 事务成功之后、下一份 RuntimeSnapshot 编译之前；通知
-    /// 不参与已提交事务成败。没有账号派生状态的 Provider 可使用默认空实现。
+    /// 不参与已提交事务成败
+    /// 没有账号派生状态的 Provider 可使用默认空实现
    async fn account_facts_changed(&self, _account_ids: &[ProviderAccountId]) {}

-    /// 生成一次连接测试所需的 Provider-owned operation；Core 负责实际执行与落账。
+    /// 生成一次连接测试所需的 Provider-owned operation；Core 负责实际执行与落账
    async fn connection_test_operation(
        &self,
        upstream_model: &UpstreamModelId,
        input_text: &str,
    ) -> Result<Operation, ProviderAdminError>;

-    /// 返回该 Provider 实际持有的 Dashboard 上游身份画像。
+    /// 返回该 Provider 实际持有的 Dashboard 上游身份画像
    fn dashboard_wire_profile(&self) -> Option<DashboardWireProfile>;

    fn configured_wire_profile(
@@ -180,8 +228,8 @@ pub trait ProviderAdmin: Send + Sync {
        self.dashboard_wire_profile()
    }

-    /// 使用 Provider-owned 价格规则恢复持久请求的逐项费用。
-    /// 未保存的长上下文计费标记不得从当前价格反推。
+    /// 使用 Provider-owned 价格规则恢复持久请求的逐项费用
+    /// 未保存的长上下文计费标记不得从当前价格反推
    fn calculated_billing(
        &self,
        input: &ProviderBillingInput,
@@ -212,7 +260,7 @@ pub trait ProviderAdmin: Send + Sync {
        command: PrepareCredentialRefresh,
    ) -> Result<PreparedCredentialRotation, ProviderAdminError>;

-    /// 可公开的账号连接设置；实现只能显式投影非敏感字段，不能返回凭据原文。
+    /// 可公开的账号连接设置；实现只能显式投影非敏感字段，不能返回凭据原文
    async fn account_configuration(
        &self,
        _account_id: &ProviderAccountId,
@@ -225,7 +273,7 @@ pub trait ProviderAdmin: Send + Sync {
        request: ProviderQuotaRequest,
    ) -> Result<ProviderQuota, ProviderAdminError>;

-    /// 历史观测的协议字段仅由具体 Provider 解释；不支持时保留累计估算。
+    /// 历史观测的协议字段仅由具体 Provider 解释；不支持时保留累计估算
    fn quota_forecast_observation(
        &self,
        _document: &ProviderDocument,
@@ -234,8 +282,8 @@ pub trait ProviderAdmin: Send + Sync {
        None
    }

-    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝。
-    /// 只由个人信息显式查询，不在额度刷新或后台任务中预取。
+    /// 查询 Provider 官方个人资料统计；不支持该能力的 Provider 使用默认拒绝
+    /// 只由个人信息显式查询，不在额度刷新或后台任务中预取
    async fn subscription(
        &self,
        _account_id: &ProviderAccountId,
@@ -250,7 +298,7 @@ pub trait ProviderAdmin: Send + Sync {
        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝。
+    /// 打开 Provider 官方头像字节流；不支持该能力的 Provider 使用默认拒绝
    async fn profile_avatar(
        &self,
        _account_id: &ProviderAccountId,
@@ -258,7 +306,7 @@ pub trait ProviderAdmin: Send + Sync {
        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    /// 查询 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝
    async fn reset_credits(
        &self,
        _account_id: &ProviderAccountId,
@@ -266,7 +314,7 @@ pub trait ProviderAdmin: Send + Sync {
        Err(ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝。
+    /// 消费 Provider 主动额度重置卡；不支持该能力的 Provider 使用默认拒绝
    async fn consume_reset_credit(
        &self,
        _command: ConsumeProviderResetCredit,
@@ -280,7 +328,7 @@ pub trait ProviderAdmin: Send + Sync {
        refresh: bool,
    ) -> Result<ProviderModels, ProviderAdminError>;

-    /// 导出该账号的 Provider 原生模型目录正文；不提供原生目录的 Provider 使用默认拒绝。
+    /// 导出该账号的 Provider 原生模型目录正文；不提供原生目录的 Provider 使用默认拒绝
    async fn model_catalog_document(
        &self,
        _account_id: &ProviderAccountId,
@@ -294,7 +342,7 @@ pub trait ProviderAdmin: Send + Sync {
    ) -> Result<ProviderExport, ProviderAdminError>;
 }

-/// 启动时注册原生 Provider，按 ProviderKind 查找管理能力。
+/// 启动时注册原生 Provider，按 ProviderKind 查找管理能力
 #[derive(Clone)]
 pub struct ProviderAdminRegistry {
    providers: Arc<BTreeMap<ProviderKind, Arc<dyn ProviderAdmin>>>,
@@ -308,11 +356,11 @@ impl ProviderAdminRegistry {
            .collect()
    }

-    /// 创建无重复 ProviderKind 的注册表。
+    /// 创建无重复 ProviderKind 的注册表
    ///
    /// # Errors
    ///
-    /// 重复注册同一 ProviderKind 时返回 Conflict。
+    /// 重复注册同一 ProviderKind 时返回 Conflict
    pub fn new(
        providers: impl IntoIterator<Item = Arc<dyn ProviderAdmin>>,
    ) -> Result<Self, ProviderAdminError> {
@@ -338,7 +386,7 @@ impl ProviderAdminRegistry {
            .ok_or_else(|| ProviderAdminError::new(ProviderAdminErrorKind::Unsupported))
    }

-    /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照。
+    /// 账号目录与关联列表共用套餐补全和展示规则，已知账号套餐优先于额度快照
    pub(crate) fn resolve_account_plan(
        &self,
        provider_kind: &str,
@@ -351,7 +399,7 @@ impl ProviderAdminRegistry {
        self.plan_type_display(provider_kind, plan_type.as_deref())
    }

-    /// 账号页和 Dashboard 共用的大驼峰套餐展示名称，不修改原始套餐值。
+    /// 账号页和 Dashboard 共用 Provider 的最终展示名称，不改写官方拼写或原始套餐值
    pub(crate) fn plan_type_display(
        &self,
        provider_kind: &str,
@@ -361,15 +409,13 @@ impl ProviderAdminRegistry {
        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(),
+        Some(provider.map_or_else(
+            || default_plan_type_display(plan_type),
            |provider| provider.plan_type_display(plan_type),
-        );
-        // 所有 Provider 及未知套餐统一排版，保留 Plus 后缀的含义。
-        Some(display.replace('+', " Plus ").to_upper_camel_case())
+        ))
    }

-    /// 返回所有已注册 Provider 的 Dashboard 上游身份画像。
+    /// 返回所有已注册 Provider 的 Dashboard 上游身份画像
    pub fn dashboard_wire_profiles(
        &self,
        configurations: &std::collections::BTreeMap<
@@ -386,7 +432,7 @@ impl ProviderAdminRegistry {
            .collect()
    }

-    /// 按平台计算请求费用。
+    /// 按平台计算请求费用
    pub fn calculated_billing(
        &self,
        provider_kind: &ProviderKind,
@@ -395,3 +441,7 @@ impl ProviderAdminRegistry {
        self.require(provider_kind)?.calculated_billing(input)
    }
 }
+
+fn default_plan_type_display(plan_type: &str) -> String {
+    plan_type.replace('+', " Plus ").to_upper_camel_case()
+}
@@ -1,3 +1,5 @@
+//! 账号出站代理的持久化、导入占用与连通性探测端口
+
 use async_trait::async_trait;
 use gateway_core::account::{OutboundProxy, ProviderAccountId};

@@ -12,7 +14,7 @@ use crate::model::{

 #[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(
@@ -20,7 +22,7 @@ pub trait ProxyStore: Send + Sync {
        query: ProxyAccountListQuery,
    ) -> AdminStoreResult<ProxyAccountPage>;
    async fn get(&self, id: &str) -> AdminStoreResult<ProxyRecord>;
-    /// 仅在账号仍绑定指定代理时解除关联，并清除账号保存的连接地址。
+    /// 仅在账号仍绑定指定代理时解除关联，并清除账号保存的连接地址
    async fn remove_account(
        &self,
        proxy_id: &str,
@@ -52,7 +54,7 @@ pub trait ProxyStore: Send + Sync {
    ) -> AdminStoreResult<ProxyMutation>;
 }

-/// 离开作用域时释放保护，错误返回和请求取消也遵循相同规则。
+/// 离开作用域时释放保护，错误返回和请求取消也遵循相同规则
 pub trait ProxyImportGuard: Send + Sync {}

 pub struct ProxyImportReservation {
@@ -0,0 +1,23 @@
+//! 有界保留期删除，不承载周期、暂停或重试策略
+
+use std::num::NonZeroU32;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+
+use super::store::AdminStoreResult;
+use crate::model::retention::{RetentionPolicy, RetentionTarget};
+
+#[async_trait]
+pub trait RetentionStore: Send + Sync {
+    async fn load_policy(&self) -> AdminStoreResult<RetentionPolicy>;
+
+    /// 每次最多删除 limit 行；请求关联事件随请求事务级联删除
+    async fn purge_batch(
+        &self,
+        target: RetentionTarget,
+        now: DateTime<Utc>,
+        policy: RetentionPolicy,
+        limit: NonZeroU32,
+    ) -> AdminStoreResult<u64>;
+}
@@ -1,19 +1,19 @@
-//! 管理控制面所需的持久化能力。
+//! 管理控制面所需的持久化能力
 //!
-//! 端口按业务资源拆分，方法使用领域模型，不暴露连接池、事务或 Redis client。
+//! 端口按业务资源拆分，方法使用领域模型，不暴露连接池、事务或 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,
+        AccountGroupListQuery, AccountGroupMemberFact, AccountGroupMutation,
+        AccountGroupOptionsPage, AccountGroupPage, DeleteAccountGroup, NewAccountGroup,
+        SetAccountGroupEnabled, UpdateAccountGroup,
    },
    accounts::{
        AccountListQuery, AccountPage, AccountPageItem, AccountRuntimeSnapshot,
@@ -22,13 +22,15 @@ use crate::model::{
    },
    auth::{AdminAuditEvent, AuthSession},
    client_keys::{
-        ClientKeyListQuery, ClientKeyPage, ClientKeyRecord, ClientKeySecret, DeleteClientKey,
-        NewClientKey, ResetClientKeyBudget, SetClientKeyEnabled, UpdateClientKey,
+        ClientKeyBudgetMutationOrigin, ClientKeyListQuery, ClientKeyPage, ClientKeyRecord,
+        ClientKeySecret, DeleteClientKey, NewClientKey, ResetClientKeyBudget, SetClientKeyEnabled,
+        UpdateClientKey, UpdateClientKeyBudgetLimits,
    },
    observability::{
-        DashboardObservation, DashboardRuntimeSlots, DiagnosticDimension, DiagnosticObservation,
-        OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange, UsageCalculatedBillingFact,
-        UsageDetail, UsageFilter, UsageOverview, UsagePage, UsageQuery,
+        DashboardObservation, DashboardQuery, DiagnosticDimension, DiagnosticsObservation,
+        Granularity, OpsErrorPage, OpsErrorQuery, RequestMetricPoint, TimeRange,
+        UsageBillingProjection, UsageCalculatedBillingFact, UsageDetail, UsageFilter,
+        UsageInsightsObservation, UsageOverview, UsagePage, UsageQuery,
    },
    provider_credentials::{
        AuthorizationCommit, CredentialDetails, CredentialImportCommit, CredentialImportResult,
@@ -39,7 +41,7 @@ use crate::model::{
    settings::{AdminApiKey, AdminApiKeyMutation, ReplaceRuntimeSettings, RuntimeSettings},
 };

-/// 管理端可判定的持久化失败类型。
+/// 管理端可判定的持久化失败类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AdminStoreErrorKind {
    Invalid,
@@ -50,13 +52,14 @@ pub enum AdminStoreErrorKind {
    Unavailable,
 }

-/// 隐藏数据库实现细节的持久化错误。
-#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
+/// 隐藏数据库实现细节的持久化错误
+#[derive(Debug, Clone, thiserror::Error)]
 #[error("{resource} store operation failed: {message}")]
 pub struct AdminStoreError {
    kind: AdminStoreErrorKind,
    resource: &'static str,
    message: String,
+    source: Option<gateway_core::error::ErrorSource>,
 }

 impl AdminStoreError {
@@ -70,9 +73,27 @@ impl AdminStoreError {
            kind,
            resource,
            message: message.into(),
+            source: None,
        }
    }

+    /// 来源留在内部诊断链，公开消息不展开基础设施错误
+    #[must_use]
+    pub fn with_source(mut self, source: impl Into<gateway_core::error::ErrorSource>) -> Self {
+        self.source = Some(source.into());
+        self
+    }
+
+    /// 清理失败不覆盖最初操作的分类与原因
+    #[must_use]
+    pub fn with_cleanup(mut self, cleanup: impl Into<gateway_core::error::ErrorSource>) -> Self {
+        self.source = Some(gateway_core::error::ErrorSource::cleanup(
+            self.source.take(),
+            cleanup,
+        ));
+        self
+    }
+
    #[must_use]
    pub const fn kind(&self) -> AdminStoreErrorKind {
        self.kind
@@ -86,10 +107,10 @@ impl AdminStoreError {

 pub type AdminStoreResult<T> = Result<T, AdminStoreError>;

-/// 账号目录与公共账号写操作。
+/// 账号目录与公共账号写操作
 #[async_trait]
 pub trait AccountStore: Send + Sync {
-    /// 插件回调按授权 Provider/账号在数据库过滤后做稳定 cursor 分页。
+    /// 插件回调按授权 Provider/账号在数据库过滤后做稳定 cursor 分页
    async fn list_plugin_accounts(
        &self,
        query: PluginAccountListQuery,
@@ -118,7 +139,7 @@ pub trait AccountStore: Send + Sync {
        windows: &[AccountUsageWindowQuery],
    ) -> AdminStoreResult<Vec<AccountUsageWindowResult>>;

-    /// 从同一数据库语句取得截止快照的累计用量和有界历史观测。
+    /// 从同一数据库语句取得截止快照的累计用量和有界历史观测
    async fn load_quota_forecast_history(
        &self,
        window: &AccountUsageWindowQuery,
@@ -130,7 +151,7 @@ pub trait AccountStore: Send + Sync {
        account_id: &gateway_core::account::ProviderAccountId,
    ) -> AdminStoreResult<Option<CredentialDetails>>;

-    /// 插件按全局账号 ID 读取时，由数据库记录提供权威 Provider 归属。
+    /// 插件按全局账号 ID 读取时，由数据库记录提供权威 Provider 归属
    async fn credential_details_by_id(
        &self,
        account_id: &gateway_core::account::ProviderAccountId,
@@ -142,7 +163,7 @@ pub trait AccountStore: Send + Sync {
        account_ids: &[gateway_core::account::ProviderAccountId],
    ) -> AdminStoreResult<Vec<ProviderExportCredentialInput>>;

-    /// 插件凭据读取只接收账号 ID，不接受调用方另行声明 Provider。
+    /// 插件凭据读取只接收账号 ID，不接受调用方另行声明 Provider
    async fn load_credential_for_plugin(
        &self,
        account_id: &gateway_core::account::ProviderAccountId,
@@ -160,7 +181,7 @@ pub trait AccountStore: Send + Sync {
        context: &MutationContext,
    ) -> AdminStoreResult<crate::model::provider_credentials::AuthorizationCommitResult>;

-    /// 已提交的授权结果独立于 Redis 临时状态；只有原管理员身份可读。
+    /// 已提交的授权结果独立于 Redis 临时状态；只有原管理员身份可读
    async fn authorization_receipt(
        &self,
        key: &crate::model::provider_credentials::AuthorizationReceiptKey,
@@ -184,7 +205,7 @@ pub trait AccountStore: Send + Sync {
        context: &MutationContext,
    ) -> AdminStoreResult<AccountUpdateResult>;

-    /// 在事务内按最新启用状态、账号上限和全局默认值判断，只降低并发上限。
+    /// 在事务内按最新启用状态、账号上限和全局默认值判断，只降低并发上限
    async fn lower_concurrency_limit(
        &self,
        account_id: &gateway_core::account::ProviderAccountId,
@@ -217,7 +238,7 @@ pub trait AccountStore: Send + Sync {
    ) -> AdminStoreResult<()>;
 }

-/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有。
+/// 可丢失账号运行态的管理读端口；跨存储编排由 Admin application service 拥有
 #[async_trait]
 pub trait AccountRuntimeStore: Send + Sync {
    async fn active_rate_limits(&self) -> AdminStoreResult<AccountRuntimeSnapshot>;
@@ -227,18 +248,18 @@ pub trait AccountRuntimeStore: Send + Sync {
        account_ids: &[String],
    ) -> AdminStoreResult<AccountRuntimeSnapshot>;

-    /// 容量熔断自动冻结中的账号与其冻结截止时间；429 临时限流不包含在内。
+    /// 容量熔断自动冻结中的账号与其冻结截止时间；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,
@@ -247,12 +268,12 @@ pub trait AccountRuntimeStore: Send + Sync {
    ) -> 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,
@@ -273,6 +294,14 @@ pub trait AuthStore: Send + Sync {

    async fn store_session(&self, session_id: &str, session: &AuthSession) -> AdminStoreResult<()>;

+    /// 原子替换或撤销仍匹配的会话并返回当前值；过期或退出后不重新创建
+    async fn compare_exchange_session(
+        &self,
+        session_id: &str,
+        expected: &AuthSession,
+        replacement: Option<&AuthSession>,
+    ) -> AdminStoreResult<Option<AuthSession>>;
+
    async fn delete_session(&self, session_id: &str) -> AdminStoreResult<Option<AuthSession>>;

    async fn client_key_enabled(
@@ -280,7 +309,7 @@ pub trait AuthStore: Send + Sync {
        id: &gateway_core::policy::ClientApiKeyId,
    ) -> AdminStoreResult<bool>;

-    /// 原子消费来源桶与全局桶的一次登录尝试；被拒绝时返回建议重试间隔。
+    /// 原子消费来源桶与全局桶的一次登录尝试；被拒绝时返回建议重试间隔
    async fn consume_login_attempt(
        &self,
        source_ip: IpAddr,
@@ -292,10 +321,10 @@ pub trait AuthStore: Send + Sync {
    async fn append_audit_event(&self, event: AdminAuditEvent) -> AdminStoreResult<()>;
 }

-/// Client API Key 资料读取与管理写入。
+/// Client API Key 资料读取与管理写入
 #[async_trait]
 pub trait ClientKeyStore: Send + Sync {
-    /// 按已验证的 ID 读取资料，不读取完整明文 Key。
+    /// 按已验证的 ID 读取资料，不读取完整明文 Key
    async fn get_client_key(
        &self,
        id: &gateway_core::policy::ClientApiKeyId,
@@ -332,15 +361,24 @@ pub trait ClientKeyStore: Send + Sync {
        context: &MutationContext,
    ) -> AdminStoreResult<Revision>;

-    /// 仅修改运行时账本并原子记录审计，不推进配置版本。
+    /// 局部更新预算上限，保留其他策略和账本；无变化时不产生配置版本或审计
+    async fn update_client_key_budget_limits(
+        &self,
+        command: UpdateClientKeyBudgetLimits,
+        origin: ClientKeyBudgetMutationOrigin,
+        context: &MutationContext,
+    ) -> AdminStoreResult<Option<Revision>>;
+
+    /// 仅修改运行时账本并原子记录审计，不推进配置版本
    async fn reset_client_key_budget(
        &self,
        command: ResetClientKeyBudget,
+        origin: ClientKeyBudgetMutationOrigin,
        context: &MutationContext,
    ) -> AdminStoreResult<()>;
 }

-/// Provider-neutral account group management transactions.
+/// 跨 Provider 的账号分组管理事务
 #[async_trait]
 pub trait AccountGroupStore: Send + Sync {
    async fn list_account_groups(
@@ -348,6 +386,11 @@ pub trait AccountGroupStore: Send + Sync {
        query: AccountGroupListQuery,
    ) -> AdminStoreResult<AccountGroupPage>;

+    async fn list_account_group_options(
+        &self,
+        query: AccountGroupListQuery,
+    ) -> AdminStoreResult<AccountGroupOptionsPage>;
+
    async fn load_account_group_members(
        &self,
        group_ids: &[gateway_core::routing::AccountGroupId],
@@ -378,46 +421,50 @@ pub trait AccountGroupStore: Send + Sync {
    ) -> AdminStoreResult<AccountGroupMutation>;
 }

-/// 逐条读取的已计算费用事实；消费结束或丢弃时释放查询资源。
-pub type UsageCalculatedBillingStream<'a> =
-    BoxStream<'a, AdminStoreResult<UsageCalculatedBillingFact>>;
+/// 后台投影复用 Admin 与 Provider 的费用规则，Store 不重新解释价格
+pub trait UsageBillingProjector: Send + Sync {
+    fn project(
+        &self,
+        fact: &UsageCalculatedBillingFact,
+    ) -> Result<UsageBillingProjection, crate::model::AdminError>;
+}

-/// 用量、趋势、诊断与运维错误的只读能力。
+/// 用量、趋势、诊断与运维错误的只读能力
 #[async_trait]
 pub trait ObservabilityStore: Send + Sync {
-    /// 返回历史统计区间和指定观测时刻下的实时账号状态。
+    /// 读取实现声明的总预算，缓存等待沿用同一配置，避免外层提前截断
+    fn query_timeout(&self) -> std::time::Duration;
+
+    /// 缓存必须与删除和后台投影提交的版本一致
+    async fn analytics_cache_generation(&self) -> AdminStoreResult<u64>;
+
+    /// 返回历史统计区间和指定观测时刻下的实时账号状态
    async fn dashboard_summary(
        &self,
-        range: TimeRange,
+        query: DashboardQuery,
        observed_at: DateTime<Utc>,
    ) -> AdminStoreResult<DashboardObservation>;

-    /// 返回 Dashboard 可选的实时槽位事实。
-    ///
-    /// 该状态来自可丢失的运行时存储；无实现或运行时存储不可用时返回 `None`，不影响
-    /// 持久观测数据的读取。
-    async fn dashboard_runtime_slots(
+    async fn dashboard_trend(
        &self,
-        _observed_at: DateTime<Utc>,
-    ) -> AdminStoreResult<Option<DashboardRuntimeSlots>> {
-        Ok(None)
-    }
-
-    async fn dashboard_trend(&self, range: TimeRange) -> AdminStoreResult<Vec<RequestMetricPoint>>;
+        range: TimeRange,
+        granularity: Granularity,
+    ) -> AdminStoreResult<Vec<RequestMetricPoint>>;

    async fn usage_trend(
        &self,
        range: TimeRange,
        filter: UsageFilter,
+        granularity: Granularity,
    ) -> AdminStoreResult<Vec<RequestMetricPoint>>;

-    /// 流式返回可由 Provider 重新校验的已计算费用事实，不保证顺序。
-    /// 查询及解码错误由流返回；调用方应逐条聚合，避免收集整个区间。
-    fn usage_calculated_billing_facts(
+    /// 同一读取快照中的汇总、趋势和已投影情景费用
+    async fn usage_insights_observation(
        &self,
        range: TimeRange,
        filter: UsageFilter,
-    ) -> UsageCalculatedBillingStream<'_>;
+        granularity: Granularity,
+    ) -> AdminStoreResult<UsageInsightsObservation>;

    async fn list_usage_records(&self, query: UsageQuery) -> AdminStoreResult<UsagePage>;

@@ -434,12 +481,13 @@ pub trait ObservabilityStore: Send + Sync {
        range: TimeRange,
        filter: UsageFilter,
        dimension: DiagnosticDimension,
-    ) -> AdminStoreResult<Vec<DiagnosticObservation>>;
+        limit: u16,
+    ) -> AdminStoreResult<DiagnosticsObservation>;

    async fn list_ops_errors(&self, query: OpsErrorQuery) -> AdminStoreResult<OpsErrorPage>;
 }

-/// Runtime settings 与管理员 API Key 写入。
+/// Runtime settings 与管理员 API Key 写入
 #[async_trait]
 pub trait SettingsStore: Send + Sync {
    async fn load_pricing(&self) -> AdminStoreResult<crate::model::pricing::StoredPricing>;
@@ -476,7 +524,7 @@ pub trait SettingsStore: Send + Sync {
    ) -> AdminStoreResult<AdminApiKeyMutation>;
 }

-/// 账号目录、运行态与分组所需的 Store 能力集合。
+/// 账号目录、运行态与分组所需的 Store 能力集合
 #[derive(Clone)]
 pub struct AdminAccountStorePorts {
    accounts: Arc<dyn AccountStore>,
@@ -502,9 +550,10 @@ impl AdminAccountStorePorts {
    }
 }

-/// 管理用例所需能力的封闭集合。
+/// 管理用例所需能力的封闭集合
 ///
-/// 字段保持私有，每个 getter 只交出一种明确能力。该类型不提供通用拆包入口。
+/// 字段保持私有，每个 getter 只交出一种明确能力
+/// 该类型不提供通用拆包入口
 #[derive(Clone)]
 pub struct AdminStorePorts {
    accounts: AdminAccountStorePorts,
@@ -515,9 +564,15 @@ pub struct AdminStorePorts {
    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)
@@ -542,6 +597,7 @@ impl AdminStorePorts {
        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,
@@ -552,6 +608,7 @@ impl AdminStorePorts {
            backup,
            plugins,
            plugin_state,
+            plugin_resources,
        }
    }

--- a/Show More
+++ b/Show More