chore(release): v3.41.1

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

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

@@ -0,0 +1,85 @@
+---
+name: cpr-dev-guide
+description: Codex Proxy RS 开发、修复、排障、代码审查和文档修改入口；页面、样式、文案、接口、调度、数据库及宿主 SDK、Runtime、插件接入均适用；PR、Issue、独立网关插件与发版叠加对应技能
+---
+
+# 开发指南
+
+## 首要写作要求：言简意赅
+
+所有面向人的文字都按此要求编写和审查，包括界面、通知、后端错误、任务状态、命令行、日志、注释、文档和交付说明
+
+- 先写读者需要知道的事实或动作。删掉一句不影响理解、判断或操作，就删；标题、正文和通知不重复同一信息
+- 保留会改变决定的条件、权限、后果和恢复步骤。错误通知只说已知问题，有明确办法才补一句；后端返回的提示在后端改，前端不重复解释。上游原文、用户内容和诊断事实保持原样
+
+## 先确定领域与必读规范
+
+按用户意图、受影响行为与对象初判，定位后按实际文件复核，不要求用户说出“前端”“后端”或技能名。**所有命中行共同构成本次必读规范，先读完再确定方案、修改或给出审查结论**；跨领域叠加，不能只选最像当前步骤的一行
+
+职责边界决定问题由谁修复；即使代码位于账号、调度或 API 模块，只要影响插件接入或为插件增加处理，也命中插件边界。确定方案时说明相关业务事实的归属及已有实现的复用依据，不能以功能恢复或测试通过替代职责判断
+
+| 领域或操作，行为影响与文件路径满足其一即可 | 确定方案前读取与执行 |
+| --- | --- |
+| 调整页面、弹窗、表单、按钮、文案、样式或交互；目标在 `frontend/`、`modules/ui/`、插件前端，或是 `.vue` 文件 | [前端流程](references/frontend.md)，覆盖组件复用、文案、Token、样式、视觉状态和运行证据；局部修改同样执行 |
+| 开发、排查或审查插件接入、宿主 SDK、Runtime、扩展接口或独立网关插件；目标在 `backend/crates/gateway-plugin/`、`modules/plugins/` | 完整读取[插件职责边界](references/plugin-boundaries.md)及所用 [SDK](../../../backend/crates/gateway-plugin/sdk/README.md) 类型与能力合同；宿主维护自身合同、资源与稳定性，插件业务错误在插件侧修复，不在宿主、SDK 或 Runtime 中补偿；独立插件开发、排查、审查另用 [cpr-plugin-dev](../cpr-plugin-dev/SKILL.md) |
+| 开发、排查或审查服务端接口、路由、调度、账号与用量规则、持久化、后台任务或协议行为；目标是 `backend/` 中的实现、配置、迁移，或 Rust 源码 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)的模块与依赖规则、所属模块及[后端自审](../../../docs/architecture.md#后端自审)；Rust 使用 `$rust-best-practices` 和下方后端注释要求，宿主 Rust 同时读取 [Rust 模块组织约定](../../../docs/architecture.md#32-rust-模块组织约定) |
+| 修改页面接口调用，或开发、排查、审查面向管理端或模型客户端的 HTTP／WS API 合同 | [API](../../../docs/api.md)对应章节；优先复用已有接口，核对调用方 → 服务端解析 → 实际查询或执行，不能只凭前端类型认定参数生效；按实际改动叠加前后端规范 |
+| 新增、修改或审查客户端可见错误、失败提示、后台任务状态文案 | 下方[错误文案](#错误文案)，并按实际出口核对[错误与诊断三层边界](../../../docs/architecture.md#错误与诊断三层边界) |
+| 模块或调用链变更 | [Workspace 边界](../../../docs/architecture.md#3-workspace-边界)及所属模块章节，不通读整份架构 |
+| 新增、调整、清理或审查测试 | 下方[测试维护](#测试维护)，按当前行为、职责归属与已有覆盖判断保留、合并或删除 |
+| 修改部署行为、`deploy/` 配置或数据库迁移 | 按范围读取[部署](../../../deploy/README.md)、[迁移](../../../backend/migrations/README.md)对应章节 |
+| 修改或审查文档；实现或审查用法、公开合同、职责、约束或运维操作的变化 | [文档检查](references/documentation.md)及相关章节，尚无文档差异时也检查是否漏更；纯文档任务不默认读取代码开发、页面验收或发布流程 |
+| 代码审查，包括 PR 审查 | [审查标准](../../../CONTRIBUTING.md#审查标准)，叠加被审查行为所属领域的规范；审查默认只读 |
+| PR / Issue / 发版 | 按当前意图选 [PR](../cpr-github-pr/SKILL.md)、[Issue](../cpr-github-issue/SKILL.md)或[发版](../cpr-release/SKILL.md)，普通提交不创建 PR |
+
+纯文档任务按文档分支执行；核实文中的合同与职责时读对应领域条款，不因提及代码路径或语言加载实现、构建与页面验收流程
+
+命中的流程引用完整读取，并落实其中指定的必读章节；长文档先用 `rg -n '^#{1,4} ' 文件` 定位，读取指定章节的完整内容。`#章节` 不会自动截取，“按需”仅用于未命中的领域和后续操作资料，不能省略必读规范；已有内容只在当前上下文可用且仍适用时复用，不循环重读技能
+
+## 参考仓库的优先级
+
+开发、排障和代码审查先按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实问题与方案。涉及 Codex 行为时执行其中的官方行为优先约束：对应版本的官方源码优先，以透明转发和最小必要适配为默认方案，先判断偏离是否必要再评价实现
+
+## 执行与收尾
+
+1. 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，按其 CodeGraph 约定定位代码；确认工作区、任务范围与已有改动，找到事实归属、同类实现和调用链，补齐上表命中规范及[项目约定](../../../CONTRIBUTING.md#项目约定)对应条目后再修改
+2. 以最终差异重新匹配上表，补齐新增领域的规范并检查实际实现，再处理本次引入的职责越界、重复规则、冗余状态与无依据分支；删除或替换功能时一并清理失效的配置、类型、调用、测试与文档，已部署数据和公开合同仍遵守所属迁移及兼容规则；仅审查时报告，不自行修复
+3. 按最终行为执行[文档检查](references/documentation.md)，核对所属正文及相关概述、示例和引用，在本任务内完成必要同步；不以尚无文档差异跳过检查。内部重构等未改变文档所述事实时无需改文档；常规文档只写当前状态，普通开发不自动修改 `release/notes.md`
+4. 按变更范围执行[验证](../../../CONTRIBUTING.md#验证)及其停止条件，后端命令见[验证命令](../../../docs/architecture.md#验证命令)；沿用本轮有效证据与用户已确定的验收分工，区分通过、失败、跳过与未执行；提交时补读[提交约定](../../../CONTRIBUTING.md#项目约定)
+5. 交付前按[首要写作要求](#首要写作要求言简意赅)通读本次新增或修改的文字。交代实际结果与验证缺口；前端按[前端流程](references/frontend.md)核对运行证据，后端按上表检查生命周期，不把构建通过当作行为验收
+
+## 测试维护
+
+- 测试随当前功能维护，名称、夹具和断言描述当前输入、行为与结果；功能变更时优先更新所属模块的现有用例，不为每次改动叠加一组记录变更经过的测试
+- 清理只证明旧字段、旧路由或旧实现已经消失的用例与附带断言；未知字段校验使用合法请求基线加无业务含义的未知字段，避免因缺少必填项等其他错误而误通过
+- 同一层对同一行为的重复覆盖合并为清晰的场景矩阵，复用相邻测试夹具；跨层测试确有不同职责或失败路径时保留，不为统一而扩大测试辅助抽象
+- 断言可观察的行为与业务不变量，避免复述结构体赋值、罗列表列或字段清单、匹配 SQL 文本与源码布局；项目明确要求的架构边界检查继续维护
+- 当前协议兼容、数据读取兼容、安全边界、并发和资源生命周期仍需覆盖，不按 `old`、`legacy` 等名称机械删除，也不能用改名代替无效用例清理
+- 不在仓库中新增或保留迁移 SQL 专项测试，包括迁移文本、schema 演变与指定版本升级用例；需要验证迁移执行、数据保留或回滚时，在临时目录编写一次性验证并使用隔离数据库，测试通过即可，临时脚本不纳入维护测试集
+- 持久化功能测试使用当前完整 schema，验证现行读写、事务与数据约束；插件运行时状态迁移等业务能力按当前功能测试，不归为迁移 SQL 专项测试
+
+## 后端注释
+
+- 每个 Rust 文件顶层使用简短的中文 `//!` 注释说明文件职责，覆盖生产源码、测试与构建脚本；测试文件说明测试范围或辅助用途，生成文件同步维护生成器
+- 注释不使用中文或英文句号，多句说明按语义分行；保留 URL、版本号、标识符和代码示例中有语义的点号
+- 文件说明聚焦当前功能与职责边界，局部注释解释原因和约束，避免复述代码或记录修改经过
+
+## 错误文案
+
+适用于项目自定义的客户端提示，包括 HTTP、WS、SSE 和任务失败状态；原始上游错误与内部诊断遵守[三层边界](../../../docs/architecture.md#错误与诊断三层边界)，不为统一外观翻译、截短或改写
+
+- 管理端自定义提示统一中文，模型 API 自定义提示统一英文；英文句首大写、句末使用句号，API、Codex 等缩写及专有名词保持正确大小写，中文短提示不加句末句号
+- 默认一句说明具体问题，确有必要才补第二句处理办法，不设机械字数限制；明确字段、对象或限制，避免只说「请求不合法」或堆叠内部术语
+- 处理办法必须明确且适用；不把「请稍后重试」「联系管理员」作为统一后缀，不罗列尚未确认的网络、权限、磁盘等可能原因，不对执行结果未知的操作笼统建议重试
+- 机器码、状态与结构化字段负责程序判断，文案供人阅读；只改措辞时保留分类、重试和账号处置语义，先核对现有调用方是否依赖消息文本
+- 在拥有错误事实的模块提供安全提示，保留独立的内部原因链；不在响应出口批量首字母大写、翻译或裁剪任意消息，以免改写上游原文
+
+| 场景 | 文案示例 |
+| --- | --- |
+| 日费用额度耗尽 | `Daily spending limit reached.` |
+| 请求过大 | `Request too large. Reduce the input size.` |
+| 客户端过旧 | `Codex CLI is outdated. Upgrade to 0.152.0 or later.` |
+| 名称为空 | `请输入 API Key 名称` |
+| 更新包校验失败 | `更新包校验失败，请重新下载` |
+
+审查时沿实际出口检查语言、大小写、标点、长度和处理建议；复用现有行为测试核对错误码及敏感信息边界，不为逐条文案建立重复的快照或字符串清单测试

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

@@ -0,0 +1,6 @@
+interface:
+  display_name: "cpr-dev-guide"
+  short_description: "开发、排障与审查入口，按行为影响匹配领域边界并验证实现"
+  default_prompt: "使用 $cpr-dev-guide 按请求、行为影响和实际文件匹配领域必读规范，读完职责边界再确定方案，完成已授权的开发或审查、自审与验证。"
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,39 @@
+# 文档检查
+
+修改或审查文档，以及实现或审查涉及文档更新条件的行为变化时，完整读取本流程和 [文档职责与更新条件](../../../../CONTRIBUTING.md#文档职责与更新条件)，覆盖内容归属与层次行文
+
+## 核实与同步范围
+
+- 以当前目标分支及任务内工作区的实现、配置和有效运行证据核实行为；提交记录用于发现待核实的主题，不能直接当作现行事实或按提交顺序组织正文。按 [CodeGraph 约定](../../../../AGENTS.md#codegraph)同步索引后定位，证据不足时报告缺口，不把计划或推测写成已支持能力
+- 开发任务按最终行为检查哪些用法、合同、职责、约束或运维操作需要同步，即使尚无 Markdown 差异也要检查；独立文档更新按用户范围核对现行说明，不等到发版时再补普通开发所需的文档
+- 沿同一事实查找所属正文及相关概述、示例和引用，重点核对“支持／不支持”等能力声明、默认值、配置模板和命令。概述保留必要摘要并链接详细合同；不能只更新详细章节，留下 README 或示例中的矛盾说明，也不扩展为无关全仓改写
+
+## 写之前
+
+先确定读者、必须说明的当前事实与所属章节，再决定是否需要修改及详略；文档职责与更新条件按上节核对。涉及合同或职责说明时，补读所属架构、API 或 SDK 的对应条款，核实事实；不因文档提及实现而执行无关的开发与构建流程
+
+在所属章节就地替换失效说明，先组织读者现在需要的操作、结果和限制，不从变更摘要改写正文。仅介绍被替代实现、修复动机或修改经过的段落直接删除；删掉“新增”“此前”“不再”等词后仍在回答变更经过的内容，也不保留
+
+## 逐段验收
+
+检查工作区和暂存区中本任务的最终文档差异，并连同受影响章节及相关概述、示例通读，按内容用途处理，不只搜索关键词：
+
+| 段落回答的问题 | 处理 |
+| --- | --- |
+| 现在如何使用、配置或理解结果 | 保留当前事实与必要边界，放回所属章节 |
+| 谁负责状态、事务、资源和失败处理 | 放入所属架构章节，避免在 API 或部署文档复述实现 |
+| 这次做了什么、以前怎样、为什么这样修、跑过哪些测试 | 移入 PR、Issue 或任务报告，不以换成现在时的方式留在常规文档 |
+| 特定配置或数据状态下如何升级、恢复 | 写明适用条件、操作及限制，删除演变过程 |
+| 别处已完整说明的事实 | 合并或改为必要摘要与链接 |
+
+脱离提交日期、Issue 和本次任务背景后，读者仍应能独立理解正文
+
+业务中的请求历史、审计记录、旧数据兼容与回滚操作是当前功能，不能因含“历史”“旧”等词而删除
+
+## 交付检查
+
+- 完成上述逐段验收及[行文检查](../../../../CONTRIBUTING.md#层次与行文)，发现问题先处理，未完成内容审查不能称文档已检查
+- 检查相对链接、章节锚点、表格与命令示例，`git diff --check` 或构建通过不能代替内容审查
+- 交付时简述已同步的文档范围；涉及更新条件却未改文档时，说明现有内容为何仍准确或还有什么缺口。仅报告实际核对范围，不把链接检查通过称为事实核实，也不把检查记录写进常规文档
+
+只有明确的发布说明任务才进入 `cpr-release`；发布说明与常规文档的边界按[内容归属](../../../../CONTRIBUTING.md#内容归属)执行

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

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

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

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

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

@@ -0,0 +1,63 @@
+---
+name: cpr-github-issue
+description: 草拟、创建、补充或回复 GitHub Issue，包括缺陷、功能和协作规则反馈；单独排障或修复不自动发布 Issue
+---
+
+# Issue 协作
+
+## 目标与范围
+
+从用户 URL、remote 和上下文确认接收仓库，fork 场景区分自己的仓库与上游
+
+草拟只准备正文，明确创建或提交才发布；已有授权直接执行，自动命中技能本身不授权远程写入
+
+补充已有 Issue 先读原帖和讨论，按授权更新或追加，不重复新建；无法推断的目标或关键事实才向用户补齐
+
+## 按动作读取与核实
+
+目标、授权、事实与脱敏要求适用于草拟、提交和回复；按下列动作读取必需规则与证据，再组织正文。症状反馈可保留未知根因，进入技术排查或方案判断时补齐对应规范
+
+- 新建 Issue 时，读取本仓库的[提交 Issue](../../../CONTRIBUTING.md#提交-issue)及本次匹配的一张表单：[接口问题](../../../.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题](../../../.github/ISSUE_TEMPLATE/general-bug-report.yml)或[功能建议](../../../.github/ISSUE_TEMPLATE/feature-request.yml)；协作规则提案可用普通 Issue
+- 回复时读取原帖、相关讨论与支撑答复的证据，按下方回复口吻组织内容，不套用新建 Issue 的表单
+- 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING
+- 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理
+- 需要技术排查、判断实现方案或修改时执行 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)的领域必读，不能仅凭症状建议跨职责补偿；提交症状反馈不以找到根因为前提
+- 引用上游行为或提出方案时执行[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，注明适用版本、来源与缺口
+
+## 正文与证据
+
+标题说明症状或期望行为，区分发生问题的部署版本、实测结果、预期结果与根因假设
+
+功能和规则提案说明场景、缺少的能力及建议结果，无需硬套缺陷复现步骤
+
+YAML 表单按 `attributes.label` 和字段顺序组织正文，手工核对必填项、选项与确认项，CLI 不会代做表单校验
+
+未知信息如实标明，影响理解或复现的关键事实先补齐，不提交原始 YAML、占位答案或未确认的勾选项
+
+日志和附件仅含定位所需的脱敏片段，不公开凭据、完整配置或请求转储，不擅自修改代理、TUN、证书环境取证
+
+附件须获授权且可访问，本机路径不算附件；labels 和 assignees 仅按模板或用户要求设置，并确认实际存在
+
+Issue 可记录复现、排查和变更经过；涉及常规文档修改时执行[文档检查](../cpr-dev-guide/references/documentation.md)
+
+## 回复口吻
+
+草拟、发布或修改 Issue 回复时，按 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)将核实结果写成面向提问者的交流答复，具体口吻规则集中维护在该节
+
+按平常回帖的口吻写，语气自然、委婉，说清判断和原因，少用铺垫、转折和自我说明；暂不采纳或提出不同意见时说明具体原因
+
+发送或更新前从提问者视角通读：判断和原因是否清楚，建议是否便于尝试，补充材料的用途是否明确。删去不影响理解的客套、重复解释和过程说明；发现生硬时调整整句，不能仅加缓和词，保留已核实的结论
+
+## 发布与收尾
+
+使用可用连接器或 `gh`，不为提交反馈安装工具、修改仓库配置或启用服务
+
+多行正文通过结构化字段或 UTF-8 文件传递，以下变量须先从已确认的目标与正文赋值：
+
+```bash
+gh issue create --repo "$issue_repo" --title "$issue_title" --body-file "$issue_body_file"
+```
+
+发布前核对目标、必填内容、脱敏与重复记录，更新时保留无关原文；不擅自评论、重开或关闭重复 Issue
+
+超时或结果不明确时先查询远端再重试，发布后回读确认并返回链接；仅草拟或发布失败时提供正文并注明未提交

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

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

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

@@ -0,0 +1,50 @@
+---
+name: cpr-github-pr
+description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处理审查意见；普通 Git 提交和无 PR 上下文的排障不创建 PR
+---
+
+# PR 协作
+
+## 先确定范围
+
+沿用当前会话的目标与授权，创建 PR 包含任务范围内的提交和推送，审查默认只读；二者都不包含合并
+
+仅准备标题或正文不写远端，“能合并吗”按审查处理，发布评论、批准或请求修改须有对应授权
+
+从 URL、remote 和上下文确认仓库，区分 fork 的推送端与 PR 接收端；存在无法消除的歧义时只补齐必要信息
+
+本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求
+
+为本仓库拟写或更新 PR 标题时，完整标题使用英文，沿用提交信息的 Conventional Commits 格式，例如 `fix(store): preserve client key ledgers after deletion`
+
+涉及上游行为的判断按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)执行
+
+## 按模式读取
+
+先完成上述范围判断，再按当前动作与差异涉及的领域叠加下表。命中的流程引用完整读取，长文档读取指定章节；只复用已实际读取且仍适用的内容，单纯整理正文或回复不扩展为完整实现审查
+
+| 当前动作 | 读取与执行 |
+| --- | --- |
+| 只整理标题或描述 | 当前 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)的领域必读与对应检查，包括后端、插件、测试和 API 等命中项；只读审查同样执行，不能仅核对 PR 正文与 CI |
+| 含前端改动 | [前端流程](../cpr-dev-guide/references/frontend.md)，核对适用规范与当前实现的运行证据 |
+| 含文档改动 | [文档检查](../cpr-dev-guide/references/documentation.md) |
+
+## 回复口吻
+
+草拟和发布 PR 讨论、审查意见的回复时，执行 [GitHub 回复口吻](../../../CONTRIBUTING.md#github-回复口吻)
+
+## 创建与审查的公共核对
+
+- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状，分别判断问题是否成立、是否属于目标项目职责及方案是否必要
+- 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR
+- 自审或审查覆盖完整差异与调用链，前端与文档按模式表检查
+- 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft
+- 验证结果对应实际 head，区分通过、失败、跳过与未执行；无文档改动时只核对现有说明是否失真
+
+远程操作优先使用可用连接器，`gh` 显式指定 `--repo`，多行正文使用结构化字段或 `--body-file`
+
+返回链接或会话内结论，说明实际范围与缺口，不将检查通过称为维护者批准

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

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

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

@@ -0,0 +1,29 @@
+# 创建或更新 PR
+
+仅在创建、推送或更新 PR 时读取，先完成[入口](../SKILL.md)的范围判断与公共核对
+
+1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
+   不用提交日志拼接正文，也不假定仓库一定有模板。
+2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
+   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
+3. 已完成的改动也须按入口公共核对复核问题与方案。原问题不成立时不包装成已修复的缺陷，证据不足时保留结论。
+   实现与自审按 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)执行，包括适用的后端生命周期和前端检查；需要修正时只修改已授权范围。
+4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
+   更新现有标题或正文须在本次整理/更新请求范围内。
+5. 按[验证](../../../../CONTRIBUTING.md#验证)执行适用检查，记录对应提交或工作区状态；文档、页面证据与模型披露按入口核对。
+6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
+   再给必要的设计取舍、自审结论、验证与遗留事项，按模板附页面截图和 AI 使用情况。涉及上游行为时，按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)写明官方源码位置、版本、处理方式及本次方案关系。按规模压缩，不强填无关章节。
+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 命令。
+创建完成返回链接、目标分支和验证摘要，不称为已合并。

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

@@ -0,0 +1,24 @@
+# 审查 PR
+
+仅在审查 PR 时读取，执行[入口](../SKILL.md)的公共核对，默认只在当前会话报告
+
+1. 获取 PR 的 base/head SHA、描述、文件差异、已有讨论及 CI 状态。记录实际审查的 head，使用 merge-base 差异。
+   需要源码上下文时先遵守目标仓库的定位规则；需检出时使用隔离工作区，保留用户当前分支和运行环境。
+   按实际行为与文件执行 [cpr-dev-guide](../../cpr-dev-guide/SKILL.md)的领域必读，再判断方案与实现；只读审查也核对职责边界与生命周期。
+2. 按入口公共核对在目标分支基线核实问题，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
+3. 按[问题与方案依据](../../../../CONTRIBUTING.md#问题与方案依据)评估解决方向，涉及上游时说明官方处理方式及本次方案关系；缺少必要性依据的偏离明确指出，不因测试通过就认定方案合理。
+4. 按[审查标准](../../../../CONTRIBUTING.md#审查标准)追踪完整调用链，找到共享业务事实、同类实现及已有验证。
+   对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
+   主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
+   不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
+5. 前端改动执行[前端流程](../../cpr-dev-guide/references/frontend.md)，浏览器可用时检查相关交互；缺少必需截图时要求补齐并列为未具备审阅条件。
+6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
+   文档差异按[文档检查](../../cpr-dev-guide/references/documentation.md)核对最终 diff。
+   核对 AI 使用与模型披露，缺项明确指出。工具不可用、集成测试跳过或环境不足时具体说明影响范围。
+7. 按审查标准用中文输出问题是否成立、方案是否合理及对应依据，再列实现问题与验证缺口；复用建议指出具体已有实现。
+   没有问题的类别可省略，未发现问题时直接说明并交代覆盖范围。
+8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
+
+审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
+用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
+需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。

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

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

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

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

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

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

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

@@ -0,0 +1,10 @@
+# 插件页面
+
+创建、修改或审查插件页面时完整读取，先完成[插件入口](../SKILL.md#先读职责边界)的边界判断并执行[前端流程](../../cpr-dev-guide/references/frontend.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 本地预览不等于已安装插件的热更新，宿主验证仍需重新构建、打包和切换版本

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

@@ -0,0 +1,25 @@
+# 清单与处理器实现
+
+开发、排查或审查插件清单、Rust 处理器时完整读取，先完成[插件入口](../SKILL.md#先读职责边界)的边界判断，涉及 Rust 时执行[开发入口](../../cpr-dev-guide/SKILL.md)的 Rust 分支
+使用能力前读取 SDK 的[能力与方法](../../../../backend/crates/gateway-plugin/sdk/docs/capabilities.md#能力与方法)及所用能力章节，已有实现的修复与审查也核对合同
+
+## 清单与处理器
+
+- `publisher` 与机器短名 `name` 派生插件 ID，`displayName` 用于展示；复制示例后同时调整扩展项 ID 与注册结果
+- `contributes` 每种能力最多一项，派生 ID 和固定阶段可省略；能力版本与中间件阶段按[扩展项简写](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)声明。自定义完整扩展项 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` 或自行组织换号重试；普通请求和响应加工仍使用中间件

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

@@ -0,0 +1,39 @@
+---
+name: cpr-release
+description: Codex Proxy RS 的版本规划、发布说明、正式或预发行发布与失败恢复；部署重启和普通 Git tag 清理不属于发版
+---
+
+# 发版
+
+## 范围与授权
+
+沿用用户确定的版本、范围与授权，准备版本或询问能否发布不执行远程写入；明确发布时完成已授权步骤，无需重复确认
+
+仅打 tag 不自动扩展为完整发版，发布也不包含运行实例升级或合并实验功能
+
+稳定版与 alpha、beta、rc 从 `main` 发布，exp 从对应 `experimental/<用途>` 分支发布
+
+其他仓库使用其发布入口与规则，不套用本仓库路径；规则已在上下文中时不重复读取
+
+## 必须保持的边界
+
+- Codex 兼容性变化按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核对已有依据与验证范围，缺少依据列为发行风险，不以 CI 通过代替
+- `release/publish --check <version>` 只读检查发行准备条件；不带 `--check` 会提交、打 tag、推送并触发工作流，实际发布仍需相应授权
+- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
+- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
+- `release/notes.md` 只承载当前发行的说明；常规文档修改另按开发入口执行[文档检查](../cpr-dev-guide/references/documentation.md)
+- 交付版本、提交、Release／工作流链接与实际结果，未完成构建或缺失产物时不称发布成功
+
+## 按任务读取
+
+先落实上述范围与边界，再读取当前阶段的完整指定章节；实际发布包含准备与验收，不能只读执行命令。阶段变化时补齐读取，准备文案不加载执行流程，实际发布前须核对发布入口的完整副作用
+
+| 任务 | 读取范围 |
+| --- | --- |
+| 推荐版本号 | [基线与版本](references/preparation.md#基线与版本) |
+| 编写或翻译发布说明 | [基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明) |
+| 检查发行条件 | [发行准备检查](references/preparation.md#发行准备检查) |
+| 实际发布 | 先完成[基线与版本](references/preparation.md#基线与版本)、[发布说明](references/preparation.md#发布说明)、[发行准备检查](references/preparation.md#发行准备检查)，再执行[通道核对](references/operations.md#发行通道核对)、[执行发版](references/operations.md#执行发版)与[恢复与验收](references/operations.md#恢复与验收) |
+| 失败恢复或验收 | [恢复与验收](references/operations.md#恢复与验收)，先确定已完成步骤，不直接重跑入口 |
+| 实验版 | 在对应阶段补读[实验流程](references/experimental.md)；实际发布必须覆盖分支与版本、发布能力、文案和执行与验收 |
+| 修复代码、工作流或常规文档 | 使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，有 PR 任务再使用 [cpr-github-pr](../cpr-github-pr/SKILL.md) |

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

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

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

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

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

@@ -0,0 +1,50 @@
+# 执行、恢复与验收
+
+只在实际发布、恢复失败步骤或验收发行时读取对应章节，先核对[入口](../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`，按[接口弃用规则](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#接口弃用)校验并维护 `plugin-api-deprecations.json`，将这些差异与最终工作区中的发布说明一起提交为 `chore(release): vX.Y.Z`。
+不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
+本任务需要的提交按[项目约定](../../../../CONTRIBUTING.md#项目约定)保留英文 Conventional Commits 与相应署名。
+
+在准备完成且用户已授权发布后，将 `release_version` 设为已确定的版本，执行：
+
+```bash
+release/publish "$release_version"
+```
+
+该命令会创建上述版本提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
+只读预检使用 `release/publish --check "$release_version"`。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
+
+只调整已发布页面的标题或正文时，编辑对应 GitHub Release 的 `name` 或 `body` 并回读核对；
+保持已有 tag、源码提交、附件和预发行状态，不重新执行发布入口。
+
+## 恢复与验收
+
+- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。
+  若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。
+- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发；
+  工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。
+- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。
+- 构建与打包中间产物保留 7 天，在有效期内可重跑失败任务；产物过期后重跑完整工作流，不移动原 tag。
+- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。
+  工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。
+- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功；
+  Release 和镜像已生成也不表示用户的运行实例已经升级。

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

@@ -0,0 +1,39 @@
+# 版本与说明准备
+
+只在规划版本、编写发布说明或准备发行时读取对应部分，不因准备文案加载执行流程
+
+## 基线与版本
+
+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` 提交说明、版本文件及[插件接口弃用清单](../../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#接口弃用)的必要更新，准备说明时不要提前单独提交或把版本文件改成目标版本
+用户只要求准备时保留本地改动，纯说明修改无需重建前后端
+
+## 发行准备检查
+
+进入实际发行准备后，读取目标分支的 [release/publish](../../../../release/publish)、[工作流](../../../../.github/workflows/release.yml)与[平台清单](../../../../release/platforms.yaml)，按当前入口执行，不另写脚本或绕过检查
+
+发布说明准备好、其他代码已提交后，执行 `release/publish --check <version>`，检查版本、说明、工作区、远端分支与 tag、工具链和插件兼容窗口。
+预检不修改文件、Git 引用或远端状态；远端存在本地未知提交时先同步再检查。它不替代 CI、发行物验证或实际发布授权
+
+按[验证要求](../../../../CONTRIBUTING.md#验证)核对目标提交的证据，区分通过、失败、跳过与未执行
+数据库变更同时读取[迁移冻结规则](../../../../backend/migrations/README.md#冻结规则)：
+
+- 对照同一大版本的上一正式版和本轮预发行／实验线的已发布版本，验证迁移未改写及升级路径
+- 区分未发布迁移、已执行迁移的源码部署实例与 CI 冻结基线，未发版不代表未执行，也不授权放宽冻结规则
+- 兼容性与 CI 检查分别报告，跨大版本不默认支持在线升级
+
+正式执行时再读取[通道核对](operations.md#发行通道核对)与[执行发版](operations.md#执行发版)，触发工作流不等于发布成功

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

@@ -1,38 +0,0 @@
----
-name: dev-guide
-description: 当前仓库开发指南。修改或排查本仓库的 Rust 网关、Vue 管理端、账号与出站代理、接口协议、部署、CI、发布或文档时使用，定位权威规范和验证入口。Use for development in the repository containing this skill; not for generic Rust/Vue questions in unrelated repositories.
----
-
-# 开发指南
-
-先读根目录的 [AGENTS.md](../../../AGENTS.md) 和 [CONTRIBUTING.md](../../../CONTRIBUTING.md)。
-本技能只组织工作入口，架构、协议和视觉规则从下列权威文档读取，不维护第二份副本。
-
-## 按任务读取
-
-| 任务 | 技能与文档入口 |
-| --- | --- |
-| 用户能力、快速开始 | [README](../../../README.md) |
-| 模块职责、调用链、状态归属 | [系统架构](../../../docs/architecture.md) |
-| Rust 开发 | 加载并使用 `$rust-best-practices`，结合 [系统架构](../../../docs/architecture.md) 与 [项目约定](../../../CONTRIBUTING.md#项目约定) |
-| HTTP 路由、请求与响应、导入导出 | [API 文档](../../../docs/api.md) |
-| 前端开发、管理端组件、主题 Token、视觉验证 | 加载并使用 `$frontend-design`，结合 [管理端主题](../../../docs/theme.md) 与 [界面验证](../../../CONTRIBUTING.md#界面验证) |
-| 常规文档更新 | [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件)：维护当前说明，在原章节就地修订，不记录变更历史 |
-| 部署、客户端配置、备份与恢复 | [部署说明](../../../deploy/README.md) |
-| 数据迁移、冻结清单与本地测试库 | [迁移说明](../../../backend/migrations/README.md) |
-| 验证命令与提交规范 | [贡献与审查](../../../CONTRIBUTING.md) |
-| 创建或审查 PR | [github-pr](../github-pr/SKILL.md) |
-| 整理或提交 Issue | [github-issue](../github-issue/SKILL.md) |
-| 发布说明、版本规划与发版 | [release](../release/SKILL.md) |
-
-## 执行顺序
-
-1. 从仓库根目录确认工作区、当前任务范围和相关运行实例；保留已有改动。
-2. 按 `AGENTS.md` 的 CodeGraph 约定定位入口、调用链和职责归属，再阅读相关实现。
-3. 按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实触发条件、问题发生版本与目标分支现状，
-   优先依据适用的官方源码确定方案。结合上表读取所需文档，先找可复用的同类实现，再修改所属模块。
-4. 文档和运行结果不一致时，追查当前源码、配置与版本，区分实现缺陷和文档过期；
-   按 [文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否修订，不为每次改动追加文档或发布说明。
-5. 按 `CONTRIBUTING.md` 验证并报告结果。后端 Cargo 命令从 `backend/` 执行，或显式指定该目录的 manifest。
-
-发布任务按 `release` 技能读取当前版本、发布入口和工作流，发布说明语言遵循 `CONTRIBUTING.md`。

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "dev-guide"
-  short_description: "从仓库规范与架构文档定位实现、验证和交付的正确入口"
-  default_prompt: "使用 $dev-guide 按当前仓库规范与架构完成开发、验证或发布。"

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

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

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "github-issue"
-  short_description: "按仓库表单整理复现证据、检查重复反馈并提交脱敏 Issue"
-  default_prompt: "使用 $github-issue 将当前问题整理为符合仓库表单的 Issue 并提交。"

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

@@ -1,103 +0,0 @@
----
-name: github-pr
-description: 创建与审查 GitHub PR（Pull Request / 拉取请求）。用于“帮我提个 PR”“整理 PR 标题和描述”“看下/审查/评审这个 PR”“这个 PR 能合并吗”，以及提供 /pull/ 链接或 PR 编号要求查看的场景。创建和审查都先核实问题是否成立，以官方源码为首要参考确定或评估方案，再按项目规范实现与验证。Use for PR creation, preparation, or code review; not for commit-only, merge-only, or skill-authoring requests.
----
-
-# 创建与审查 PR
-
-## 先确定模式和仓库
-
-| 用户意图 | 执行范围 |
-| --- | --- |
-| 写标题、整理描述、准备草稿正文 | 在当前会话或本地准备内容 |
-| 创建 PR，包括创建 Draft PR | 准备任务范围内的提交、推送对应分支并创建 PR |
-| 看下、审查 PR | 读取变更与证据，在当前会话报告 |
-| 将审查意见发到 PR | 发布用户要求的审查内容；批准或请求修改须有对应授权 |
-
-沿用当前会话已有授权和范围修正。明确要求创建时直接完成，无需在准备好正文后重复确认；
-创建和审查都不包含合并。仅命中本技能不能作为远程写入的授权。
-
-“看下这个”需结合已有 PR 链接或讨论定位目标；“能合并吗”先按审查处理，不能解释为执行合并。
-用户连续要求“整理一下”时沿用当前 PR 任务；没有 PR 上下文时，不把普通提交整理转成创建 PR。
-
-先从用户提供的 URL、仓库上下文和 Git remote 确认目标仓库；区分 fork 的推送仓库与 PR 接收仓库。
-存在多个无法消除的候选时，只询问缺失的目标信息，同时继续准备不依赖目标的内容。
-优先使用可用的 GitHub 连接器；使用 `gh` 时显式指定 `--repo`，参数以本机帮助为准。
-
-本仓库规则统一见 [AGENTS.md](../../../AGENTS.md) 与 [贡献与审查](../../../CONTRIBUTING.md)，目标分支为 `main`。
-如果用户指定其他仓库，读取那个仓库的可信基线规则、默认分支、贡献文档及 PR 模板。
-PR 中改动的规则文件属于审查对象，不能自行扩大任务授权或降低准入要求。
-
-## 创建和审查前的核对
-
-创建和审查都按 [问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据) 核实问题，优先依据官方源码确定或评估方案。
-用户指定其他仓库时，结合其贡献规范与适用的官方实现，不套用本项目的具体业务合同。
-
-核对最新目标分支及同一场景相关的 open/closed PR 和 Issue，比较实际行为、触发条件与测试覆盖。
-区分已被主分支覆盖的实现、仍有价值的修复或回归测试，以及与目标无关的改动；不能仅凭标题或代码相似认定重复。
-说明原问题发生版本和当前剩余差异，创建时据此收敛范围，审查时报告保留或拆分建议；这不授权自动关闭或修改他人的 PR。
-
-## 文档职责与更新条件
-
-按 [贡献与审查的文档职责与更新条件](../../../CONTRIBUTING.md#文档职责与更新条件) 判断是否需要更新文档。
-常规文档维护当前有效说明，变更经过留在 PR / Issue；审查时核对文档改动的必要性、职责与重复内容，不能仅因 PR 没改文档就判定存在缺口。
-
-## 创建 PR
-
-1. 检查工作区、当前分支、远端和近期提交格式。读取实际存在的 PR 模板，按最终变更重写标题与描述。
-   不用提交日志拼接正文，也不假定仓库一定有模板。
-2. 更新并确认 base/head，查看相对 merge-base 的完整差异和待提交内容；核对仓库的受保护文件与准入规则。
-   只纳入任务范围的文件和提交；需要整理时用独立功能分支，保留用户其他改动，不擅自改写已发布历史。
-3. 按上述核对流程，在目标分支基线核实问题，追踪官方与本项目的相关调用链，先确定解决方向再实现。
-   若改动已完成，也要据此复核问题与方案；需要修正时只修改已授权的范围。仅整理标题或正文时报告差异与缺口，
-   不自行修改实现。原问题不成立时不将它包装成已修复的缺陷；证据不足时明确保留结论。
-   实现应职责清晰、表达直接、复用合理；提交前主动清理本次变更引入的重复逻辑、冗余状态、死代码、
-   多余抽象及无依据的兼容分支。功能可用和检查通过不能替代可维护性自查。
-4. 查找同一来源仓库、head 和 base 的现有 PR；已存在则复用其链接，不重复创建。
-   更新现有标题或正文须在本次整理/更新请求范围内。
-5. 按贡献文档执行适用检查。记录实际验证的提交或工作区状态，区分通过、失败、跳过和未执行。
-   前端改动提供实际界面证据或预览步骤；缺少证据时写明，不用构建成功替代视觉验收。
-6. 将任务范围内的提交推送到正确远端，核对远端 head。标题遵循项目约定，正文先说明问题成立的依据和最终行为，
-   再给必要的设计取舍、验证与遗留事项。涉及官方行为时，写明官方源码位置与版本或提交、官方处理方式、
-   本次实现与它的关系及必要的偏离原因；区分源码推断和实际复现，不用检查通过替代方案论证。按规模压缩，不强填无关章节。
-7. 明确要求草稿或仍有阻塞项时创建 Draft PR，并解释原因；具备审查条件且未要求草稿时创建普通 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 是否遵循其协议语义和职责归属、
-   是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
-4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
-   对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
-   主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
-   不能仅因功能可用、CI 通过而略过，也不把个人写法偏好判为缺陷。
-5. UI 改动同时对照主题、共用组件、数据展示逻辑和同类页面。浏览器可用时检查相关交互及状态；
-   未运行的页面检查列为验证缺口，不从截图或源码推断所有状态都正确。
-6. 核对 CI 与本地证据是否覆盖当前 head；根据风险补充必要验证，不触发无关部署或真实账号业务请求。
-   工具不可用、集成测试跳过或环境不足时具体说明影响范围。
-7. 按 [审查标准](../../../CONTRIBUTING.md#审查标准) 用中文先回答原问题是否成立、解决方向是否合理，
-   再列出实现问题与验证缺口，结论附具体依据。
-   实现问题区分必须修复项、可选建议和验证缺口；没有的类别可省略。
-   每个问题给变更中的文件位置、触发条件或规范依据、影响和最小修复方向。
-   复用建议指出具体已有实现，不把个人偏好写成缺陷；未发现问题时直接说明并交代覆盖范围。
-8. 结束前核对 head 是否变化。发生变化时检查新增差异并更新结论，或明确结论只适用于原 SHA。
-
-审查本身不修改源码、不发表评论、不提交 GitHub 的批准或请求修改状态。
-用户明确要求发布时，先复核当前 head 和重复评论，再通过结构化字段或 `--body-file` 发布对应内容；
-需要绑定具体提交时使用支持 commit ID 的审查接口。不要在旧提交结论上批准新的 head。

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

@@ -1,4 +0,0 @@
-interface:
-  display_name: "github-pr"
-  short_description: "创建与审查拉取请求，先核实问题，以官方源码为首要依据确定或评估实现方案"
-  default_prompt: "使用 $github-pr 按当前请求创建或审查 PR，先核实问题是否成立，以官方源码为首要参考确定或评估解决方案，说明源码依据及必要的偏离原因，并按仓库规范实现与验证或报告审查结论。"

.agents/skills/release/SKILL.md

@@ -1,80 +0,0 @@
----
-name: release
-description: 准备或执行当前仓库发版，维护中文发布说明。用于“发版”“发个新版本”“准备 vX.Y.Z”“推荐版本号”“整理更新日志/发布说明”“更新 release/notes.md”“打版本 tag”等发行任务。Use for version planning, release notes, and publishing a repository release; not for deploying/restarting an instance, publishing application data, or authoring a release skill.
----
-
-# 发版
-
-## 识别任务范围
-
-| 用户意图 | 执行范围 |
-| --- | --- |
-| 推荐版本号 | 根据本次变更与已有版本给出建议及理由 |
-| 整理更新日志、写 note、准备发版 | 核对变更、编写说明、检查发布条件；未要求提交时保留本地改动 |
-| 正式发布、发布指定版本、打版本 tag | 在已授权范围内执行对应步骤；仅打 tag 的请求不自动扩展为完整发版 |
-| 重试失败的发版 | 核对上次执行状态，从未完成的步骤恢复 |
-
-沿用当前会话明确的版本、范围与授权；用户已要求正式发版且条件满足时直接执行，不重复确认。
-“准备好了”“可以发版吗”属于准备或检查，不能解释成正式发布；创建本技能也不触发发版。
-发行版发布与运行实例升级分开判断，“上线”需结合上下文确定用户指哪一种。
-
-## 读取当前流程
-
-先读 [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) |
-
-命令从仓库根目录执行；每次以当前脚本和工作流为准，不另写发布脚本或绕过已有质量检查。
-用户明确指定其他仓库时先读取其发布流程，不能直接套用这里的路径和命令。
-
-## 准备版本与说明
-
-1. 确认发布分支、upstream、目标仓库、工作区和完整待推送范围。本仓库沿用 `main`；
-   未提交或未跟踪内容分别核对，不因脚本只检查已跟踪文件就认定所有内容都已纳入发布。
-2. 读取版本文件、已有 tag 和实际发行记录，确认上一发布基线与本次目标提交。
-   根据基线到目标的提交和最终差异归纳变更，剔除回退、重复和未进入发布范围的内容。
-   不能只用当前版本文件或最近几条提交判断“本次更新”。
-3. 使用用户指定或当前会话已确定的目标版本；需要建议时按兼容性、能力新增和修复范围说明理由。
-   目标 tag 必须未被占用；遇到已有同名版本先判断是重试还是新发版，不自动递增版本掩盖冲突。
-4. 按贡献文档维护 `release/notes.md`。正文写中文，保留版本号和必要技术标识；
-   按用户可感知的最终行为归并，不逐条翻译 commit，也不把排查过程或未验证承诺写入说明。
-   可按新增功能、问题修复、体验优化、升级说明组织，省略没有内容的章节。
-5. 替换为本次版本说明，首行与目标 tag 一致且正文非空。升级事项应能追溯到实际迁移、配置或兼容变化；
-   敏感信息脱敏，未合入功能不宣称已发布。已有准确说明仅需翻译时保持其事实和范围。
-6. 按贡献规范检查变更与现有 CI 证据，明确通过、失败、跳过和未执行。
-   只修改说明时无需重建前后端；正式发版仍要跟踪发布工作流针对目标提交的检查与产物。
-
-## 执行正式发版
-
-调用入口前重新核对当前脚本的副作用、目标版本和待推送提交，保留无关工作区内容，不自动清理或暂存用户文件。
-先编辑 `release/notes.md`，保留为未提交改动（已暂存或未暂存均可）；其他已跟踪文件的改动应先单独提交。
-脚本会更新 `release/version.yaml`，将它与最终工作区中的发布说明一起提交为 `chore(release): prepare vX.Y.Z`。
-不要提前单独提交说明或把版本文件改成目标版本；脚本要求说明相对 HEAD 有改动，并自行更新版本号。
-本任务需要的提交按贡献文档保留英文 Conventional Commits 与相应署名。
-
-在准备完成且用户已授权正式发布后，将 `release_version` 设为已确定的版本，执行：
-
-```bash
-release/publish "$release_version"
-```
-
-该命令会创建包含版本号和发布说明的单次提交与 annotated tag，原子推送分支和 tag，再从长期分支手动触发 `release.yml`。
-它没有只读预演模式；不能为了检查或演练而执行。发布工作流读取 tag 中的说明，修改 tag 之后的本地文件不会改变该次构建。
-
-## 恢复与验收
-
-- 脚本中断或网络超时时，先核对本地提交与 tag、远端分支与 tag、对应工作流 run 及 Release，确定已完成到哪一步。
-  若本地已创建版本提交或 tag，不直接重跑入口，也不通过删 tag、回退版本或强推来消除报错。
-- 提交和 tag 已推送但工作流未触发时，核对目标后使用脚本提示的 dispatch 命令补触发；
-  工作流已存在则跟踪或恢复对应 run，避免重复发布。发现 tag 指向不同提交时报告冲突，不移动已发布 tag。
-- 跟踪与本次 tag 对应的 run ID，核对工作流解析的目标提交。触发工作流成功只表示已开始，不能当作发布完成。
-- 发布完成后核对 GitHub Release 的版本、正式版/预发行状态和中文变更正文；对照平台清单与工作流确认归档、校验和及镜像产物。
-  工作流附加的安装说明和自动提交列表按其当前配置处理，不用它们替代手写的中文变更说明。
-- 返回版本、tag 对应提交、Release/工作流链接及实际结果。失败、仍在构建或缺失产物时明确说明，不能称为发布成功；
-  Release 和镜像已生成也不表示用户的运行实例已经升级。

.agents/skills/release/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "release"
-  short_description: "按仓库流程整理中文发布说明、核对版本并完成发行与验证"
-  default_prompt: "使用 $release 准备下一个版本的中文发布说明，并核对发版条件。"

.gitattributes

@@ -0,0 +1,3 @@
+# SQLx migration checksums are byte-sensitive; keep migration inputs portable across hosts.
+backend/migrations/*.sql text eol=lf
+backend/migrations/.frozen-sha256 text eol=lf

.github/DISCUSSION_TEMPLATE/使用问答.yml

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

.github/DISCUSSION_TEMPLATE/实验反馈.yml

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

.github/DISCUSSION_TEMPLATE/想法讨论.yml

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

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

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

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,120 +0,0 @@
-name: 问题反馈
-description: 提交可复现的问题，帮助定位和修复
-body:
-  - type: markdown
-    attributes:
-      value: |
-        请提供最小复现信息。请求、日志和截图发布前请移除密钥、令牌、Cookie、代理认证及私人内容。
-
-  - type: dropdown
-    id: issue-type
-    attributes:
-      label: 问题类型
-      options:
-        - 接口请求或响应异常
-        - 页面或交互异常
-        - 配置或部署异常
-        - 其他问题
-    validations:
-      required: true
-
-  - type: textarea
-    id: description
-    attributes:
-      label: 问题描述
-      description: 说明发生了什么、实际结果以及出现的频率。
-    validations:
-      required: true
-
-  - type: input
-    id: version
-    attributes:
-      label: 服务版本
-      description: 填写具体版本号；从源码运行时填写提交号。
-      placeholder: 版本号或提交号
-    validations:
-      required: true
-
-  - type: dropdown
-    id: deployment
-    attributes:
-      label: 部署方式
-      options:
-        - Docker Compose
-        - 其他容器部署
-        - 二进制运行
-        - 源码运行
-        - 其他方式（请在环境信息中说明）
-    validations:
-      required: true
-
-  - type: textarea
-    id: environment
-    attributes:
-      label: 环境信息
-      description: 填写操作系统与版本；页面问题同时填写浏览器与版本。
-      placeholder: |
-        操作系统与版本：
-        浏览器与版本（页面问题）：
-    validations:
-      required: true
-
-  - type: textarea
-    id: account-client
-    attributes:
-      label: 账号与客户端
-      description: 接口问题请填写平台、认证类型、模型和客户端信息，不要提供账号凭据。
-      placeholder: |
-        平台与认证类型：
-        模型名称：
-        客户端名称与版本：
-
-  - type: textarea
-    id: reproduction
-    attributes:
-      label: 复现步骤
-      description: 描述触发问题的操作；无法稳定复现时，说明已知触发条件。
-      placeholder: |
-        1. 使用什么配置或输入
-        2. 执行什么操作
-        3. 出现什么结果
-    validations:
-      required: true
-
-  - type: textarea
-    id: expected-behavior
-    attributes:
-      label: 预期行为
-      description: 说明原本期望得到的结果。
-    validations:
-      required: true
-
-  - type: textarea
-    id: request-response
-    attributes:
-      label: 请求与响应
-      description: |
-        接口问题请提供脱敏后的最小请求、网关实际状态/响应片段和客户端终端显示，区分两者。
-        优先附管理端默认诊断包并检查其缺失说明；原始错误与日志片段需另行审阅脱敏。
-        先按部署文档的“请求错误排查”检查关联 ID、错误详情与 application 日志，不默认开启完整 dump。
-      placeholder: |
-        发生时间与时区：
-        传输（HTTP JSON / SSE / WebSocket）：
-        网关关联 ID（x-gateway-request-id / 配置的入口头）：
-        上游关联 ID（x-request-id / x-oai-request-id，注明来源）：
-        网关实际状态与响应片段：
-        客户端终端显示：
-        诊断包或无法取得的信息：
-      render: text
-
-  - type: textarea
-    id: screenshots
-    attributes:
-      label: 截图或录屏
-      description: 页面或交互问题可在此拖入相关截图、录屏，并说明对应的操作。
-
-  - type: textarea
-    id: additional-context
-    attributes:
-      label: 补充信息
-      description: 最近的升级或配置变更；网络问题补充系统代理、TUN 和自定义证书等相关环境。

.github/ISSUE_TEMPLATE/config.yml

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

.github/ISSUE_TEMPLATE/feature-request.yml

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

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

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

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

@@ -0,0 +1,76 @@
+name: Build binary
+description: Build a native release binary with shared dependency caching and timings
+inputs:
+  rust:
+    description: Pinned Rust toolchain
+    required: true
+  target:
+    description: Rust target triple
+    required: true
+  platform:
+    description: Release platform name, such as linux-amd64
+    required: true
+  binary:
+    description: Executable filename
+    default: codex-proxy-rs
+  rust-image:
+    description: Pinned Linux builder image; empty for native builds
+    default: ''
+runs:
+  using: composite
+  steps:
+    - name: Setup Rust
+      uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+      with:
+        toolchain: ${{ inputs.rust }}
+        targets: ${{ inputs.target }}
+
+    - name: Configure Windows runtime linkage
+      if: runner.os == 'Windows'
+      shell: bash
+      # 发行包静态链接 MSVC 运行库，解压运行时无需安装 VC++ Redistributable
+      run: echo 'RUSTFLAGS=-C target-feature=+crt-static' >> "$GITHUB_ENV"
+
+    - name: Cache Rust dependencies
+      uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
+      with:
+        workspaces: backend -> target
+        shared-key: release-${{ inputs.target }}-${{ inputs.rust-image }}
+        cache-bin: false
+        # 只缓存依赖，避免随版本变化的 workspace 产物挤占缓存
+        save-if: ${{ github.event_name != 'pull_request' }}
+
+    - name: Build binary
+      shell: bash
+      working-directory: backend
+      env:
+        BUILD_TARGET: ${{ inputs.target }}
+        BUILD_PLATFORM: ${{ inputs.platform }}
+        BUILD_BINARY: ${{ inputs.binary }}
+        RUST_IMAGE: ${{ inputs.rust-image }}
+      run: |
+        set -euo pipefail
+        if [ -n "$RUST_IMAGE" ]; then
+          mkdir -p "$HOME/.cargo"
+          docker run --rm --user "$(id -u):$(id -g)" \
+            -e CARGO_HOME=/cargo -e HOME=/tmp \
+            -e CPR_VERSION -e CPR_GIT_SHA -e CPR_BUILD_TIME -e CPR_BUILD_TYPE \
+            -v "$HOME/.cargo:/cargo" -v "$PWD/..:/workspace" \
+            -w /workspace/backend "$RUST_IMAGE" \
+            cargo build --release --locked --timings --target "$BUILD_TARGET" --bin codex-proxy-rs
+        else
+          cargo build --release --locked --timings --target "$BUILD_TARGET" --bin codex-proxy-rs
+        fi
+        "target/$BUILD_TARGET/release/$BUILD_BINARY" --help
+        "target/$BUILD_TARGET/release/$BUILD_BINARY" --version
+        mkdir -p "../dist/binaries/$BUILD_PLATFORM"
+        cp "target/$BUILD_TARGET/release/$BUILD_BINARY" "../dist/binaries/$BUILD_PLATFORM/$BUILD_BINARY"
+
+    - name: Upload build timings
+      if: always()
+      uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+      with:
+        name: build-timings-${{ inputs.platform }}
+        path: backend/target/cargo-timings/
+        if-no-files-found: ignore
+        retention-days: 7

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

@@ -0,0 +1,46 @@
+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: Read build toolchains
+      id: toolchains
+      shell: bash
+      run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
+    - name: Setup Node
+      uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+      with:
+        node-version: ${{ steps.toolchains.outputs.node }}
+        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@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+      with:
+        name: frontend-dist
+        path: frontend/dist
+        if-no-files-found: error
+        retention-days: 7

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

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

.github/dependabot.yml

@@ -1,8 +1,10 @@
 version: 2
 
+# 标签由维护者手动添加，各生态关闭默认打标，避免重新创建旧标签。
 updates:
   - package-ecosystem: github-actions
     directory: /
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -16,6 +18,7 @@ updates:
 
   - package-ecosystem: cargo
     directory: /backend
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -50,6 +53,7 @@ updates:
 
   - package-ecosystem: npm
     directory: /frontend
+    labels: []
     schedule:
       interval: weekly
       day: monday
@@ -64,7 +68,9 @@ updates:
           - patch
 
   - package-ecosystem: docker
-    directory: /deploy
+    directories:
+      - /deploy
+    labels: []
     schedule:
       interval: weekly
       day: monday

.github/pull_request_template.md

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

.github/scripts/package-release.rb

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

.github/scripts/publish-release.rb

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

.github/scripts/release-checks-test.rb

@@ -0,0 +1,193 @@
+require 'fileutils'
+require 'json'
+require 'open3'
+require 'tmpdir'
+require_relative 'release-quality'
+
+# 使用临时 Git 仓库验证远端状态和只读边界，不访问真实 GitHub 或修改当前仓库
+ROOT = File.expand_path('../..', __dir__)
+
+def assert(condition, message)
+  raise message unless condition
+end
+
+def git(*arguments)
+  output, error, status = Open3.capture3('git', *arguments)
+  raise "git #{arguments.first}: #{error}" unless status.success?
+  output.strip
+end
+
+def commit(message)
+  git('add', '.')
+  git('commit', '-qm', message)
+end
+
+Dir.mktmpdir('release-checks-') do |directory|
+  remote = File.join(directory, 'remote.git')
+  system('git', 'init', '--bare', '-q', remote, exception: true)
+  checkout = File.join(directory, 'checkout')
+  FileUtils.mkdir_p(checkout)
+  Dir.chdir(checkout) do
+    git('init', '-q', '-b', 'main')
+    git('config', 'user.email', 'test@example.invalid')
+    git('config', 'user.name', 'Release test')
+    files = %w[
+      release/publish release/version.yaml release/notes.md release/platforms.yaml
+      .github/scripts/toolchains.rb .github/scripts/release-metadata.rb
+      backend/rust-toolchain.toml deploy/Dockerfile
+      backend/crates/gateway-plugin/runtime/plugin-api-lifecycle.rb
+      backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json
+      backend/crates/gateway-plugin/runtime/plugin-api-deprecations.json
+    ]
+    files.each do |path|
+      FileUtils.mkdir_p(File.dirname(path))
+      FileUtils.cp(File.join(ROOT, path), path)
+    end
+    commit('initial source')
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'root commit should require full checks')
+    git('remote', 'add', 'origin', remote)
+    git('push', '-qu', 'origin', 'main')
+    File.write('release/notes.md', "# v99.0.0\n\nFixture notes\n")
+
+    bin = File.join(directory, 'bin')
+    FileUtils.mkdir_p(bin)
+    File.write(File.join(bin, 'gh'), <<~RUBY)
+      #!/usr/bin/env ruby
+      case ARGV
+      when ['auth', 'status'] then exit 0
+      when ['repo', 'view', #{remote.inspect}, '--json', 'nameWithOwner', '--jq', '.nameWithOwner']
+        puts 'owner/repo'
+      else
+        abort "unexpected gh mutation: \#{ARGV.inspect}"
+      end
+    RUBY
+    File.chmod(0o755, File.join(bin, 'gh'))
+    environment = { 'PATH' => "#{bin}:#{ENV.fetch('PATH')}" }
+    snapshot = lambda do
+      [git('show-ref'), git('status', '--porcelain'), File.binread('.git/index'),
+       files.to_h { |path| [path, File.binread(path)] },
+       git('ls-remote', 'origin'), File.exist?('.git/FETCH_HEAD')]
+    end
+    check = lambda do |success, message = nil|
+      before = snapshot.call
+      output, error, status = Open3.capture3(environment, 'bash', 'release/publish', '--check', '99.0.0')
+      assert(status.success? == success, "preflight outcome: #{output}#{error}")
+      assert("#{output}#{error}".include?(message), "missing error: #{message}; #{error}") if message
+      assert(snapshot.call == before, 'preflight modified files, refs, index, or FETCH_HEAD')
+    end
+    check.call(true, 'Preflight passed')
+    File.write('deploy/Dockerfile', File.read('deploy/Dockerfile') + "\n# fixture\n")
+    check.call(false, 'unstaged changes')
+    git('checkout', '--', 'deploy/Dockerfile')
+    git('tag', 'v99.0.0')
+    check.call(false, 'local tag already exists')
+    git('push', '-q', 'origin', 'refs/tags/v99.0.0')
+    git('tag', '-d', 'v99.0.0')
+    check.call(false, 'remote tag already exists')
+    git('push', '-q', 'origin', ':refs/tags/v99.0.0')
+
+    # 未履行的兼容窗口必须在只读预检中失败，不能等待提交版本后再发现
+    deprecations = 'backend/crates/gateway-plugin/runtime/plugin-api-deprecations.json'
+    previous = File.read(deprecations)
+    File.write(deprecations, JSON.generate([{
+      capability: 'removed-fixture', version: 1, replacement_version: 2, remaining_releases: 7
+    }]))
+    git('add', deprecations)
+    git('commit', '-qm', 'invalid lifecycle fixture')
+    check.call(false, 'replacement v2 must be available')
+    File.write(deprecations, previous)
+    commit('restore lifecycle and notes')
+    File.write('release/notes.md', "# v99.0.0\n\nUpdated fixture notes\n")
+
+    # 远端前进但没有本地对象时，提示同步而不隐式 fetch
+    other = File.join(directory, 'other')
+    git('clone', '-q', '-b', 'main', remote, other)
+    Dir.chdir(other) do
+      git('config', 'user.email', 'test@example.invalid')
+      git('config', 'user.name', 'Release test')
+      File.write('remote-only', 'change')
+      commit('remote advance')
+      git('push', '-q')
+    end
+    check.call(false, 'unseen commits')
+    git('fetch', '-q', 'origin')
+    check.call(false, 'diverged')
+    FileUtils.mv(remote, "#{remote}.hidden")
+    # 读取远端失败不能当作 tag 不存在，仍须保持本地不变
+    before = [git('show-ref'), git('status', '--porcelain'), File.binread('.git/index')]
+    _, error, status = Open3.capture3(environment, 'bash', 'release/publish', '--check', '99.0.0')
+    assert(!status.success? && error.include?('failed to read remote refs'), 'remote failure was ignored')
+    assert(before == [git('show-ref'), git('status', '--porcelain'), File.binread('.git/index')], 'remote failure changed local state')
+    FileUtils.mv("#{remote}.hidden", remote)
+
+    File.write('release/version.yaml', "version: \"99.0.0\"\n")
+    commit('release metadata')
+    parent = git('rev-parse', 'HEAD^')
+    run = { 'head_sha' => parent, 'conclusion' => 'success', 'head_repository' => { 'full_name' => 'owner/repo' }, 'id' => 42 }
+    job = { 'name' => 'quality / backend', 'conclusion' => 'success', 'html_url' => 'https://example.invalid/42' }
+    runs = [run]
+    jobs = [job]
+    original_capture = ReleaseQuality.method(:capture)
+    ReleaseQuality.define_singleton_method(:capture) do |*arguments|
+      if arguments.first == 'gh'
+        endpoint = arguments.find { |argument| argument.start_with?('repos/') }
+        if endpoint.include?('/workflows/ci.yml/runs?')
+          assert(endpoint.include?("event=push&branch=main&head_sha=#{parent}"), 'wrong CI evidence scope')
+          JSON.generate('workflow_runs' => runs)
+        else
+          assert(endpoint == 'repos/owner/repo/actions/runs/42/jobs?per_page=100', 'wrong run jobs')
+          jobs.map { |entry| JSON.generate(entry) }.join("\n")
+        end
+      else
+        original_capture.call(*arguments)
+      end
+    end
+    assert(ReleaseQuality.evidence('owner/repo') == job['html_url'], 'valid CI evidence not reused')
+    %w[skipped failure cancelled].each do |conclusion|
+      job['conclusion'] = conclusion
+      assert(ReleaseQuality.evidence('owner/repo').nil?, "reused #{conclusion} backend")
+    end
+    job['conclusion'] = 'success'
+    jobs = []
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused missing backend job')
+    jobs = [job]
+    run['conclusion'] = 'failure'
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused failed CI run')
+    run['conclusion'] = nil
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused unfinished CI run')
+    run['conclusion'] = 'success'
+    run['head_repository']['full_name'] = 'fork/repo'
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused foreign repository CI')
+    run['head_repository']['full_name'] = 'owner/repo'
+    runs = []
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused absent CI run')
+    runs = [run]
+    output, _, status = Open3.capture3(environment.merge('GITHUB_REPOSITORY' => 'owner/repo'), 'ruby', File.join(ROOT, '.github/scripts/release-quality.rb'))
+    assert(status.success? && output.strip == 'run_backend=true', 'API failure did not fall back to full checks')
+    File.write('backend/source.rs', '// changed source')
+    commit('source changed')
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'reused CI across source changes')
+    merge = git('commit-tree', 'HEAD^{tree}', '-p', 'HEAD', '-p', 'HEAD^', '-m', 'merge fixture')
+    git('update-ref', 'HEAD', merge)
+    assert(ReleaseQuality.evidence('owner/repo').nil?, 'merge commit should require full checks')
+
+    # 在同一个隔离仓库走实际提交与原子推送路径，dispatch 仍由本地替身接收
+    git('merge', '--no-edit', 'origin/main')
+    File.write('release/notes.md', "# v100.0.0\n\nPublish fixture notes\n")
+    dispatch = File.join(directory, 'dispatch.json')
+    mock = File.join(bin, 'gh')
+    File.write(mock, File.read(mock).sub("else\n", <<~RUBY))
+      when ['workflow', 'run', 'release.yml', '--repo', 'owner/repo', '--ref', 'main', '--raw-field', 'tag=v100.0.0']
+        File.write(#{dispatch.inspect}, ARGV.join(' '))
+      else
+    RUBY
+    output, error, status = Open3.capture3(environment, 'bash', 'release/publish', '100.0.0')
+    assert(status.success?, "publish failed: #{output}#{error}")
+    assert(File.exist?(dispatch), 'workflow was not dispatched')
+    assert(git('log', '-1', '--format=%s') == 'chore(release): v100.0.0', 'wrong release commit')
+    assert(git('status', '--porcelain').empty?, 'release left tracked changes')
+    assert(git('rev-parse', 'HEAD') == git('rev-parse', 'v100.0.0^{commit}'), 'tag differs from release commit')
+    assert(git('ls-remote', 'origin', 'refs/tags/v100.0.0').split.first == git('rev-parse', 'v100.0.0'), 'tag not pushed')
+  end
+end
+puts 'Release preflight and CI evidence checks passed'

.github/scripts/release-metadata.rb

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

.github/scripts/release-quality.rb

@@ -0,0 +1,44 @@
+require 'json'
+require 'open3'
+
+# 仅复用同一源码的主分支 CI，缺少证据时完整检查发行提交
+module ReleaseQuality
+  def self.capture(*command)
+    output, error, status = Open3.capture3(*command)
+    raise "#{command.first} failed: #{error.strip}" unless status.success?
+    output
+  end
+
+  def self.evidence(repository)
+    parents = capture('git', 'rev-list', '--parents', '-n', '1', 'HEAD').split
+    return nil unless parents.length == 2
+    parent = parents.last
+    changes = capture('git', 'diff', '--name-only', '-z', parent, 'HEAD').split("\0")
+    return nil if changes.empty? || (changes - %w[release/version.yaml release/notes.md]).any?
+
+    # 按最新一次运行判断，失败或仍在执行时不回退到旧的成功记录
+    endpoint = "repos/#{repository}/actions/workflows/ci.yml/runs?event=push&branch=main&head_sha=#{parent}&per_page=1"
+    run = JSON.parse(capture('gh', 'api', endpoint)).fetch('workflow_runs').first
+    return nil unless run && run.fetch('head_sha') == parent && run.fetch('conclusion') == 'success'
+    return nil unless run.fetch('head_repository').fetch('full_name') == repository
+
+    rows = capture('gh', 'api', '--paginate', "repos/#{repository}/actions/runs/#{run.fetch('id')}/jobs?per_page=100", '--jq', '.jobs[] | @json')
+    job = rows.lines.map { |line| JSON.parse(line) }.find { |entry| entry.fetch('name') == 'quality / backend' }
+    return nil unless job && job.fetch('conclusion') == 'success'
+    job.fetch('html_url')
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  begin
+    evidence = ReleaseQuality.evidence(ENV.fetch('GITHUB_REPOSITORY'))
+  rescue StandardError => error
+    warn "CI evidence unavailable; running full release checks: #{error.message}"
+    evidence = nil
+  end
+  puts "run_backend=#{evidence.nil?}"
+  if ENV['GITHUB_STEP_SUMMARY']
+    message = evidence ? "后端质量检查复用版本提交父提交的 [CI 结果](#{evidence})；仅版本与发布说明不同" : '未找到可复用的后端 CI 结果，完整检查发行提交'
+    File.open(ENV.fetch('GITHUB_STEP_SUMMARY'), 'a') { |file| file.puts(message) }
+  end
+end

.github/scripts/toolchains.rb

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

.github/workflows/_container.yml

@@ -1,4 +1,4 @@
-name: Reusable Container
+name: Container
 
 on:
   workflow_call:
@@ -7,20 +7,73 @@ on:
         description: Exact commit SHA to build and validate
         required: true
         type: string
+      source_build:
+        description: Validate the complete Docker source build
+        type: boolean
+        default: true
 
 permissions:
   contents: read
   security-events: write
 
 jobs:
+  frontend:
+    if: ${{ !inputs.source_build }}
+    runs-on: ubuntu-26.04
+    timeout-minutes: 15
+    env:
+      CI: 'true'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref }}
+      - uses: ./.github/actions/build-frontend
+        with:
+          upload-artifact: 'true'
+
+  binary:
+    if: ${{ !inputs.source_build }}
+    runs-on: ubuntu-26.04
+    timeout-minutes: 45
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref }}
+      - id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+      - uses: ./.github/actions/build-binary
+        with:
+          rust: ${{ steps.toolchains.outputs.rust }}
+          target: x86_64-unknown-linux-gnu
+          platform: linux-amd64
+          rust-image: ${{ steps.toolchains.outputs.rust_image }}
+        env:
+          CPR_GIT_SHA: ${{ inputs.ref }}
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: codex-proxy-rs-linux-amd64
+          path: dist/binaries/linux-amd64/
+          if-no-files-found: error
+          retention-days: 7
+
   container:
-    runs-on: ubuntu-latest
+    needs: [frontend, binary]
+    if: always() && !cancelled()
+    runs-on: ubuntu-26.04
     timeout-minutes: 45
     env:
       CPR_IMAGE: codex-proxy-rs:ci-${{ inputs.ref }}
       TRIVY_QUIET: 'true'
       TRIVY_SKIP_VERSION_CHECK: 'true'
     steps:
+      # 上游失败必须传递给已有的容器检查，不能让必需状态变成 skipped
+      - name: Require prebuilt inputs
+        if: ${{ !inputs.source_build }}
+        env:
+          FRONTEND_RESULT: ${{ needs.frontend.result }}
+          BINARY_RESULT: ${{ needs.binary.result }}
+        run: test "$FRONTEND_RESULT" = success && test "$BINARY_RESULT" = success
+
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -28,46 +81,53 @@ jobs:
 
       - name: Setup Docker Buildx
         id: buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
-      - name: Cache Cargo mounts
-        id: cargo-cache
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+      - name: Download frontend
+        if: ${{ !inputs.source_build }}
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          path: ${{ runner.temp }}/container-cargo
-          key: container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-${{ inputs.ref }}
-          restore-keys: |
-            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('backend/Cargo.lock', 'backend/**/Cargo.toml', 'deploy/Dockerfile') }}-
-            container-cargo-v1-${{ runner.os }}-${{ runner.arch }}-
+          name: frontend-dist
+          path: dist/docker/web/dist
 
-      # 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
+      - name: Download binary
+        if: ${{ !inputs.source_build }}
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
-          builder: ${{ steps.buildx.outputs.name }}
-          scratch-dir: ${{ runner.temp }}/container-cache-dance
-          cache-map: |
-            {
-              "${{ runner.temp }}/container-cargo/registry": "/usr/local/cargo/registry",
-              "${{ runner.temp }}/container-cargo/git": "/usr/local/cargo/git",
-              "${{ runner.temp }}/container-cargo/target": "/app/backend/target"
-            }
-          skip-extraction: ${{ steps.cargo-cache.outputs.cache-hit }}
+          name: codex-proxy-rs-linux-amd64
+          path: dist/docker-artifacts/codex-proxy-rs-linux-amd64
+
+      - name: Prepare prebuilt image
+        if: ${{ !inputs.source_build }}
+        env:
+          MATRIX_OS: linux
+          MATRIX_ARCH: amd64
+          MATRIX_BINARY: codex-proxy-rs
+        run: |
+          ruby -r './.github/scripts/release-metadata' -e '
+            ReleaseMetadata.seal_manifest(
+              "version" => ReleaseMetadata.version(YAML.load_file("release/version.yaml").fetch("version")),
+              "git_sha" => ReleaseMetadata.git("rev-parse", "HEAD")
+            )'
+          ruby .github/scripts/package-release.rb image
 
       - name: Build runtime image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           file: deploy/Dockerfile
-          target: runtime
+          target: ${{ inputs.source_build && 'runtime' || 'runtime-prebuilt' }}
+          build-args: |
+            CPR_PREBUILT_DIR=dist/docker
+            CPR_GIT_SHA=${{ inputs.ref }}
           load: true
           tags: ${{ env.CPR_IMAGE }}
           no-cache-filters: |
             runtime-base
             runtime
-          cache-from: type=gha,scope=runtime-ci
-          cache-to: type=gha,mode=max,scope=runtime-ci
+            runtime-prebuilt
+          cache-from: type=gha,scope=runtime-${{ inputs.source_build && 'source' || 'prebuilt' }}
+          cache-to: ${{ (github.event_name == 'push' || github.event_name == 'schedule') && github.ref == 'refs/heads/main' && format('type=gha,mode=max,scope=runtime-{0}', inputs.source_build && 'source' || 'prebuilt') || '' }}
 
       - name: Verify runtime image
         uses: ./.github/actions/verify-container

.github/workflows/_quality.yml

@@ -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
@@ -29,17 +24,18 @@ permissions:
 jobs:
   backend:
     if: inputs.run_backend
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 30
     env:
       CARGO_TERM_COLOR: always
-      # Rust 1.97 编译 AWS SDK 调试信息需要更大的 codegen 线程栈。
+      CARGO_PROFILE_DEV_DEBUG: '1'
+      # 编译 AWS SDK 调试信息需要更大的 codegen 线程栈
       RUST_MIN_STACK: 16777216
       CPR_TEST_DATABASE_URL: postgres://codex_proxy:codex_proxy@127.0.0.1:5432/codex_proxy
       CPR_TEST_REDIS_URL: redis://127.0.0.1:6379
     services:
       postgres:
-        image: postgres:18-bookworm@sha256:d9c83446333daec3f0588cc709adb80c26090b7f9f0f7ec8d43c243385d79818
+        image: postgres:18-bookworm@sha256:bbf83594798e144bff365a9c191c5d779f181fb3135902064ab8ff11918020fc
         env:
           POSTGRES_DB: codex_proxy
           POSTGRES_USER: codex_proxy
@@ -53,7 +49,7 @@ jobs:
           --health-timeout 5s
           --health-retries 10
       redis:
-        image: redis:8-alpine@sha256:9d317178eceac8454a2284a9e6df2466b93c745529947f0cd42a0fa9609d7005
+        image: redis:8-alpine@sha256:0bf6577d7774e592b29d093e3ac9390eb91e13d72c21e506afce736de5e0eeb0
         ports:
           - 6379:6379
         options: >-
@@ -102,15 +98,23 @@ jobs:
             fi
           fi
 
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
       - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
+        uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
         with:
+          toolchain: ${{ steps.toolchains.outputs.rust }}
           components: rustfmt,clippy
 
       - name: Cache Rust
-        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
         with:
           workspaces: backend -> target
+          shared-key: quality
+          cache-bin: false
+          save-if: ${{ github.event_name != 'pull_request' && github.ref == 'refs/heads/main' }}
 
       - name: Rust format
         working-directory: backend
@@ -120,6 +124,19 @@ jobs:
         working-directory: backend
         run: cargo clippy --all-targets --all-features --locked -- -D warnings
 
+      - name: Setup nextest
+        uses: taiki-e/install-action@682ce6c3c696a4cd5168a05f98e51aa02b877941 # v2.89.1
+        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 --timings --list-type binaries-only --message-format json \
+            > "$RUNNER_TEMP/nextest-binaries.json"
+
       - name: Configure PostgreSQL and Redis test authentication
         shell: bash
         run: |
@@ -142,13 +159,62 @@ jobs:
             echo "CPR_TEST_REDIS_URL=redis://:${redis_password}@127.0.0.1:6379"
           } >> "$GITHUB_ENV"
 
+      - name: Expose matching PostgreSQL backup and restore tools
+        shell: bash
+        env:
+          CPR_TEST_POSTGRES_CONTAINER: ${{ job.services.postgres.id }}
+        run: |
+          set -euo pipefail
+          client_dir="$RUNNER_TEMP/pg-client"
+          mkdir -p "$client_dir"
+          for tool in pg_dump psql; do
+            printf '#!/bin/sh\nexec docker exec -i --env PGPASSWORD "%s" %s "$@"\n' "$CPR_TEST_POSTGRES_CONTAINER" "$tool" > "$client_dir/$tool"
+            chmod +x "$client_dir/$tool"
+          done
+          echo "$client_dir" >> "$GITHUB_PATH"
+
       - name: Rust tests
         working-directory: backend
-        run: cargo test --test main --locked
+        run: |
+          printf '[profile.ci.junit]\npath = "junit.xml"\n' > "$RUNNER_TEMP/nextest-ci.toml"
+          cargo nextest run --config-file "$RUNNER_TEMP/nextest-ci.toml" \
+            --cargo-metadata "$RUNNER_TEMP/nextest-cargo-metadata.json" \
+            --binaries-metadata "$RUNNER_TEMP/nextest-binaries.json" \
+            --test-threads 8 --no-tests fail --profile ci
+
+      - name: Upload test and build reports
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: backend-quality-reports
+          path: |
+            backend/target/nextest/ci/junit.xml
+            backend/target/cargo-timings/
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - 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" \
+            --test-threads 8 --no-tests fail -E 'package(=gateway-store) & test(/^redis::/)'
 
   frontend:
     if: inputs.run_frontend
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 15
     env:
       CI: 'true'
@@ -158,38 +224,11 @@ jobs:
         with:
           ref: ${{ inputs.ref }}
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
-        with:
-          version: 11.7.0
-
-      - 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
+    runs-on: ubuntu-26.04
     timeout-minutes: 5
     steps:
       - name: Checkout
@@ -197,6 +236,10 @@ jobs:
         with:
           ref: ${{ inputs.ref }}
 
+      # GitHub 已支持 queue: max，actionlint 尚未支持该字段
+      # https://github.com/rhysd/actionlint/issues/657
+      # GitHub 已提供 ubuntu-26.04，actionlint 尚未收录该标签
+      # https://github.com/actions/runner-images#available-images
       - name: Lint GitHub Actions workflows
         run: >-
           docker run --rm
@@ -204,7 +247,18 @@ jobs:
           --workdir /repo
           rhysd/actionlint:1.7.7@sha256:887a259a5a534f3c4f36cb02dca341673c6089431057242cdc931e9f133147e9
           -color
+          -ignore '^unexpected key "queue" for "concurrency" section\. expected one of "cancel-in-progress", "group"$'
+          -ignore '^label "ubuntu-26\.04" is unknown\.'
           .github/workflows/*.yml
 
-      - name: Check 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
+          for script in .github/scripts/*.rb; do ruby -c "$script"; done
+          ruby .github/scripts/toolchains.rb
+          ruby -c backend/crates/gateway-plugin/runtime/plugin-api-lifecycle.rb
+
+      - name: Verify release preflight and CI evidence
+        run: ruby .github/scripts/release-checks-test.rb

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

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

.github/workflows/ci.yml

@@ -20,12 +20,16 @@ concurrency:
 
 jobs:
   changes:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
     outputs:
       backend: ${{ steps.filter.outputs.backend }}
       frontend: ${{ steps.filter.outputs.frontend }}
       container: ${{ steps.filter.outputs.container }}
+      source_container: ${{ steps.filter.outputs.source_container }}
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -37,21 +41,55 @@ jobs:
         id: filter
         uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4.0.3
         with:
+          # 目录规则取并集，再统一排除说明文档，保留隐藏配置
+          predicate-quantifier: some-with-excludes
           filters: |
             backend:
+              - '.github/scripts/toolchains.rb'
+              - 'deploy/Dockerfile'
               - 'backend/**'
               - 'release/version.yaml'
-              - '.github/workflows/**'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/_quality.yml'
+              - '!**/*.md'
             frontend:
+              - '.github/scripts/toolchains.rb'
+              - 'backend/rust-toolchain.toml'
+              - 'deploy/Dockerfile'
               - 'frontend/**'
-              - '.github/workflows/**'
+              - '.github/actions/build-frontend/**'
+              - '.github/workflows/ci.yml'
+              - '.github/workflows/_quality.yml'
+              - '!**/*.md'
             container:
               - 'backend/**'
               - 'frontend/**'
               - 'deploy/**'
               - '.dockerignore'
               - 'release/version.yaml'
-              - '.github/actions/**'
+              - '.github/actions/verify-container/**'
+              - '.github/actions/build-binary/**'
+              - '.github/actions/build-frontend/**'
+              - '.github/scripts/toolchains.rb'
+              - '.github/scripts/package-release.rb'
+              - '.github/scripts/release-metadata.rb'
+              - '.github/workflows/_container.yml'
+              - '.github/workflows/ci.yml'
+              - '!**/*.md'
+            source_container:
+              - 'deploy/Dockerfile'
+              - 'deploy/Dockerfile.dockerignore'
+              - '.dockerignore'
+              - 'backend/**/Cargo.toml'
+              - 'backend/Cargo.lock'
+              - 'backend/rust-toolchain.toml'
+              - 'backend/**/build.rs'
+              - 'backend/.cargo/**'
+              - 'frontend/package.json'
+              - 'frontend/pnpm-lock.yaml'
+              - 'frontend/pnpm-workspace.yaml'
+              - 'frontend/.npmrc'
+              - 'frontend/patches/**'
               - '.github/workflows/_container.yml'
               - '.github/workflows/ci.yml'
 
@@ -61,7 +99,8 @@ jobs:
     with:
       ref: ${{ github.event.pull_request.head.sha || github.sha }}
       run_backend: ${{ needs.changes.outputs.backend == 'true' }}
-      run_frontend: ${{ needs.changes.outputs.frontend == 'true' }}
+      # 预构建容器复用同一次前端检查产物，源码 Docker 构建仍独立验证
+      run_frontend: ${{ needs.changes.outputs.frontend == 'true' && (needs.changes.outputs.container != 'true' || needs.changes.outputs.source_container == 'true') }}
 
   container:
     needs: changes
@@ -72,3 +111,4 @@ jobs:
     uses: ./.github/workflows/_container.yml
     with:
       ref: ${{ github.event.pull_request.head.sha || github.sha }}
+      source_build: ${{ needs.changes.outputs.source_container == 'true' }}

.github/workflows/release.yml

@@ -21,8 +21,11 @@ env:
 
 jobs:
   release-info:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-26.04
     timeout-minutes: 10
+    permissions:
+      contents: read
+      actions: read
     outputs:
       tag: ${{ steps.version.outputs.tag }}
       version: ${{ steps.version.outputs.version }}
@@ -32,9 +35,14 @@ jobs:
       platform_matrix: ${{ steps.version.outputs.platform_matrix }}
       docker_matrix: ${{ steps.version.outputs.docker_matrix }}
       non_docker_matrix: ${{ steps.version.outputs.non_docker_matrix }}
+      windows_matrix: ${{ steps.version.outputs.windows_matrix }}
       docker_platforms: ${{ steps.version.outputs.docker_platforms }}
       previous_tag: ${{ steps.version.outputs.previous_tag }}
       prerelease: ${{ steps.version.outputs.prerelease }}
+      build_type: ${{ steps.version.outputs.build_type }}
+      rust: ${{ steps.toolchains.outputs.rust }}
+      rust_image: ${{ steps.toolchains.outputs.rust_image }}
+      run_backend: ${{ steps.quality.outputs.run_backend }}
 
     steps:
       - name: Checkout
@@ -43,132 +51,114 @@ jobs:
           ref: ${{ inputs.tag }}
           fetch-depth: 0
 
-      - name: Read release metadata
+      - name: Read release metadata and seal plugin manifest
         id: version
-        shell: bash
         env:
           RELEASE_TAG: ${{ inputs.tag }}
-        run: |
-          ruby <<'RUBY' >> "$GITHUB_OUTPUT"
-          require "json"
-          require "open3"
-          require "rubygems"
-          require "time"
-          require "yaml"
+        run: ruby .github/scripts/release-metadata.rb outputs "$RELEASE_TAG" >> "$GITHUB_OUTPUT"
 
-          APP_NAME = "codex-proxy-rs"
-          SEMVER = /\A(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\z/
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
 
-          def fail(message)
-            warn(message)
-            exit(1)
-          end
+      - name: Check reusable backend CI evidence
+        id: quality
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: ruby .github/scripts/release-quality.rb >> "$GITHUB_OUTPUT"
 
-          def require_string(data, key, path)
-            value = data[key]
-            fail("#{path}: #{key} must be a non-empty string") unless value.is_a?(String) && !value.strip.empty?
-            value.strip
-          end
-
-          def version_sort_key(version)
-            Gem::Version.new(version.split("+", 2).first)
-          rescue ArgumentError
-            nil
-          end
-
-          version_path = "release/version.yaml"
-          platforms_path = "release/platforms.yaml"
-          version_data = YAML.load_file(version_path)
-          platforms_data = YAML.load_file(platforms_path)
-
-          version = require_string(version_data, "version", version_path).delete_prefix("v")
-          tag_prefix = "v"
-          expected_tag = "#{tag_prefix}#{version}"
-          release_tag = ENV.fetch("RELEASE_TAG")
-          fail("Release tag #{release_tag} does not match #{version_path} tag #{expected_tag}") unless release_tag == expected_tag
-          fail("#{version_path}: version #{version} is not a valid semver") unless version.match?(SEMVER)
-
-          notes_path = "release/notes.md"
-          fail("#{notes_path}: release notes are required") unless File.file?(notes_path)
-          notes = File.readlines(notes_path)
-          unless notes.first&.strip == "# #{release_tag}" && !notes.drop(1).join.strip.empty?
-            fail("#{notes_path}: expected non-empty notes starting with '# #{release_tag}'")
-          end
-
-          platforms = platforms_data["platforms"]
-          fail("#{platforms_path}: platforms must be a non-empty array") unless platforms.is_a?(Array) && !platforms.empty?
-
-          required_platform_keys = %w[os arch runner target binary archive]
-          seen_platforms = {}
-          docker_platform_jobs = []
-          non_docker_platform_jobs = []
-          docker_platforms = []
-          platforms.each_with_index do |platform, index|
-            fail("#{platforms_path}: platforms[#{index}] must be a table") unless platform.is_a?(Hash)
-            required_platform_keys.each do |key|
-              require_string(platform, key, "#{platforms_path}: platforms[#{index}]")
-            end
-            archive = platform["archive"]
-            fail("#{platforms_path}: platforms[#{index}].archive must be tar.gz") unless archive == "tar.gz"
-            platform_key = "#{platform["os"]}-#{platform["arch"]}"
-            fail("#{platforms_path}: duplicate platform #{platform_key}") if seen_platforms[platform_key]
-            seen_platforms[platform_key] = true
-            platform["artifact"] = "#{APP_NAME}-#{platform_key}"
-            if platform["docker"] == true
-              docker_platform = require_string(platform, "dockerPlatform", "#{platforms_path}: platforms[#{index}]")
-              platform["dockerPlatform"] = docker_platform
-              docker_platform_jobs << platform
-              docker_platforms << docker_platform
-            else
-              non_docker_platform_jobs << platform
-            end
-          end
-
-          fail("#{platforms_path}: at least one platform must set docker = true") if docker_platforms.empty?
-
-          git_sha, status = Open3.capture2("git", "rev-parse", "HEAD")
-          fail("failed to resolve git sha") unless status.success?
-          matrix = JSON.generate({ "include" => platforms })
-          docker_matrix = JSON.generate({ "include" => docker_platform_jobs })
-          non_docker_matrix = JSON.generate({ "include" => non_docker_platform_jobs })
-          current_sort_key = version_sort_key(version)
-          tags, status = Open3.capture2("git", "tag", "--list", "#{tag_prefix}*", "--merged", "HEAD")
-          fail("failed to list git tags") unless status.success?
-          previous_tag = tags
-            .lines
-            .map(&:strip)
-            .reject(&:empty?)
-            .reject { |tag| tag == release_tag }
-            .filter_map do |tag|
-              tag_version = tag.delete_prefix(tag_prefix)
-              next unless tag_version.match?(SEMVER)
-              sort_key = version_sort_key(tag_version)
-              next unless sort_key && current_sort_key && sort_key < current_sort_key
-              [sort_key, tag]
-            end
-            .max_by(&:first)
-            &.last
-
-          puts "tag=#{release_tag}"
-          puts "version=#{version}"
-          # Docker tags forbid "+", so semver build metadata maps to "-" in image tags.
-          puts "docker_version=#{version.tr("+", "-")}"
-          puts "build_time=#{Time.now.utc.iso8601}"
-          puts "git_sha=#{git_sha.strip}"
-          puts "platform_matrix=#{matrix}"
-          puts "docker_matrix=#{docker_matrix}"
-          puts "non_docker_matrix=#{non_docker_matrix}"
-          puts "docker_platforms=#{docker_platforms.join(",")}"
-          puts "previous_tag=#{previous_tag}"
-          puts "prerelease=#{version.split("+", 2).first.include?("-")}"
-          RUBY
+      - name: Upload sealed plugin assets
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: plugin-release-assets
+          path: dist/plugin-release-assets
+          if-no-files-found: error
+          retention-days: 7
 
   quality:
     needs: [release-info]
     uses: ./.github/workflows/_quality.yml
     with:
       ref: ${{ needs.release-info.outputs.git_sha }}
-      upload_frontend: true
+      run_backend: ${{ needs.release-info.outputs.run_backend == 'true' }}
+      run_frontend: false
+
+  windows:
+    needs: release-info
+    name: windows-tests (${{ matrix.arch }})
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.release-info.outputs.windows_matrix) }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    env:
+      RUST_MIN_STACK: '16777216'
+      RUSTFLAGS: '-C target-feature=+crt-static'
+      CARGO_PROFILE_DEV_DEBUG: '1'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ needs.release-info.outputs.git_sha }}
+      - uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master
+        with:
+          toolchain: ${{ needs.release-info.outputs.rust }}
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
+        with:
+          workspaces: backend -> target
+          shared-key: platform-tests-${{ matrix.target }}
+          cache-bin: false
+          save-if: ${{ github.event_name != 'pull_request' }}
+      - name: Setup nextest
+        uses: taiki-e/install-action@682ce6c3c696a4cd5168a05f98e51aa02b877941 # v2.89.1
+        with:
+          tool: cargo-nextest@0.9.143
+          fallback: none
+      - name: Verify Windows platform behavior
+        shell: bash
+        working-directory: backend
+        env:
+          BUILD_TARGET: ${{ matrix.target }}
+        # 同一次构建统一两个 package 的依赖特性，保留原有平台用例和静态运行库
+        run: |
+          printf '[profile.ci.junit]\npath = "junit.xml"\n' > "$RUNNER_TEMP/nextest-ci.toml"
+          cargo nextest run --config-file "$RUNNER_TEMP/nextest-ci.toml" --locked --target "$BUILD_TARGET" \
+            -p gateway-admin -p gateway-host --test main --no-tests fail --profile ci \
+            -E '(package(=gateway-admin) & test(/^use_case::plugins::official::/)) | (package(=gateway-host) & test(/^system_update::/))'
+      - name: Upload test report
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: windows-tests-${{ matrix.arch }}
+          path: backend/target/nextest/ci/junit.xml
+          if-no-files-found: ignore
+          retention-days: 7
+
+  security:
+    needs: release-info
+    uses: ./.github/workflows/security.yml
+    permissions:
+      contents: read
+      security-events: write
+    with:
+      ref: ${{ needs.release-info.outputs.git_sha }}
+
+  frontend:
+    needs: release-info
+    runs-on: ubuntu-26.04
+    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 }})
@@ -185,51 +175,27 @@ jobs:
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
-      - name: Cache Cargo
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: |
-            ~/.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 }}
-          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 }}-
-
       - name: Build binary
-        shell: bash
-        run: |
-          mkdir -p "$HOME/.cargo" "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}"
-          docker run --rm \
-            --platform "${{ matrix.dockerPlatform }}" \
-            --user "$(id -u):$(id -g)" \
-            -e CARGO_HOME=/cargo \
-            -e HOME=/tmp \
-            -e CPR_VERSION="${CPR_VERSION}" \
-            -e CPR_GIT_SHA="${CPR_GIT_SHA}" \
-            -e CPR_BUILD_TIME="${CPR_BUILD_TIME}" \
-            -e CPR_BUILD_TYPE="${CPR_BUILD_TYPE}" \
-            -v "$HOME/.cargo:/cargo" \
-            -v "$PWD/..:/workspace" \
-            -w /workspace/backend \
-            rust:1.97-bookworm@sha256:77fac8b98f9f46062bb680b6d25d5bcaabfc400143952ebc572e924bcbedc3fa \
-            cargo build --release --locked --target "${{ matrix.target }}" --bin codex-proxy-rs
-          cp "target/${{ matrix.target }}/release/${{ matrix.binary }}" "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/${{ matrix.binary }}"
-        working-directory: backend
+        uses: ./.github/actions/build-binary
+        with:
+          rust: ${{ needs.release-info.outputs.rust }}
+          target: ${{ matrix.target }}
+          platform: ${{ matrix.os }}-${{ matrix.arch }}
+          binary: ${{ matrix.binary }}
+          rust-image: ${{ needs.release-info.outputs.rust_image }}
         env:
           CPR_VERSION: ${{ needs.release-info.outputs.version }}
           CPR_GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           CPR_BUILD_TIME: ${{ needs.release-info.outputs.build_time }}
-          CPR_BUILD_TYPE: release
+          CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/
           if-no-files-found: error
-          retention-days: 1
+          retention-days: 7
 
   build-binary:
     name: build-binary (${{ matrix.os }}-${{ matrix.arch }})
@@ -246,47 +212,30 @@ jobs:
         with:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
-      - name: Setup Rust
-        uses: dtolnay/rust-toolchain@1a3a6d54512beeaffd394f8d516ca16f2c506a20 # 1.97
-        with:
-          targets: ${{ matrix.target }}
-
-      - name: Cache Cargo
-        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
-        with:
-          path: |
-            ~/.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 }}
-          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 }}-
-
       - name: Build binary
-        shell: bash
-        run: |
-          cargo build --release --locked --target "${{ matrix.target }}" --bin codex-proxy-rs
-          mkdir -p "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}"
-          cp "target/${{ matrix.target }}/release/${{ matrix.binary }}" "../dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/${{ matrix.binary }}"
-        working-directory: backend
+        uses: ./.github/actions/build-binary
+        with:
+          rust: ${{ needs.release-info.outputs.rust }}
+          target: ${{ matrix.target }}
+          platform: ${{ matrix.os }}-${{ matrix.arch }}
+          binary: ${{ matrix.binary }}
         env:
           CPR_VERSION: ${{ needs.release-info.outputs.version }}
           CPR_GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           CPR_BUILD_TIME: ${{ needs.release-info.outputs.build_time }}
-          CPR_BUILD_TYPE: release
+          CPR_BUILD_TYPE: ${{ needs.release-info.outputs.build_type }}
 
       - name: Upload binary artifact
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/binaries/${{ matrix.os }}-${{ matrix.arch }}/
           if-no-files-found: error
-          retention-days: 1
+          retention-days: 7
 
   package-assets:
-    needs: [release-info, quality, build-docker-binary, build-binary]
-    runs-on: ubuntu-latest
+    needs: [release-info, frontend, build-docker-binary, build-binary]
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     permissions:
       contents: read
@@ -300,103 +249,30 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download frontend artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: frontend-dist
           path: dist/frontend
 
       - name: Download binary artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           pattern: codex-proxy-rs-*
           path: dist/binaries
 
+      - name: Download sealed plugin assets
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        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 }}
-        run: |
-          set -euo pipefail
-          ruby <<'RUBY' > release-platforms.json
-          require "json"
-          require "yaml"
-
-          print JSON.generate(YAML.load_file("release/platforms.yaml"))
-          RUBY
-          python3 - <<'PY'
-          import hashlib
-          import json
-          import os
-          import pathlib
-          import shutil
-          import tarfile
-
-          APP_NAME = "codex-proxy-rs"
-
-          def sha256(path: pathlib.Path) -> str:
-              digest = hashlib.sha256()
-              with path.open("rb") as file:
-                  for chunk in iter(lambda: file.read(1024 * 1024), b""):
-                      digest.update(chunk)
-              return digest.hexdigest()
-
-          version = os.environ["VERSION"]
-          platforms = json.loads(pathlib.Path("release-platforms.json").read_text())["platforms"]
-          frontend_dir = pathlib.Path("dist/frontend")
-          binary_artifacts_dir = pathlib.Path("dist/binaries")
-          release_dir = pathlib.Path("dist/release")
-          package_dir = pathlib.Path("package")
-
-          shutil.rmtree(release_dir, ignore_errors=True)
-          release_dir.mkdir(parents=True)
-          config_template = pathlib.Path("deploy/config.example.yaml")
-          shutil.copy2(config_template, release_dir / config_template.name)
-          compose = pathlib.Path("deploy/compose.yaml").read_text()
-          image = f"{os.environ['REGISTRY']}/{os.environ['IMAGE_NAME']}"
-          default_image = "${CPR_IMAGE:-" + image + ":latest}"
-          if compose.count(default_image) != 1:
-              raise SystemExit("Expected exactly one default application image in deploy/compose.yaml")
-          # 发布附件固定镜像版本，防止后续 pull 与随包配置模板脱节。
-          versioned_image = "${CPR_IMAGE:-" + f"{image}:{os.environ['DOCKER_VERSION']}" + "}"
-          compose = compose.replace(default_image, versioned_image)
-          (release_dir / "compose.yaml").write_text(compose)
-          assets = [release_dir / config_template.name, release_dir / "compose.yaml"]
-
-          for platform in platforms:
-              platform_name = f"{platform['os']}-{platform['arch']}"
-              artifact_name = f"{APP_NAME}-{platform_name}"
-              binary_src = binary_artifacts_dir / artifact_name / platform["binary"]
-              if not binary_src.is_file():
-                  raise SystemExit(f"Missing binary artifact: {binary_src}")
-
-              shutil.rmtree(package_dir, ignore_errors=True)
-              package_root = package_dir / APP_NAME
-              web_dist = package_root / "web" / "dist"
-              web_dist.mkdir(parents=True)
-
-              binary_dest = package_root / platform["binary"]
-              shutil.copy2(binary_src, binary_dest)
-              binary_dest.chmod(0o755)
-              shutil.copytree(frontend_dir, web_dist, dirs_exist_ok=True)
-              deploy_dir = package_root / "deploy"
-              deploy_dir.mkdir()
-              shutil.copy2(config_template, deploy_dir / config_template.name)
-
-              archive_name = f"{APP_NAME}_{version}_{platform['os']}_{platform['arch']}.{platform['archive']}"
-              archive_path = release_dir / archive_name
-              if platform["archive"] == "tar.gz":
-                  with tarfile.open(archive_path, "w:gz") as archive:
-                      archive.add(package_root, arcname=APP_NAME)
-              else:
-                  raise SystemExit(f"Unsupported archive format: {platform['archive']}")
-              assets.append(archive_path)
-
-          checksum_path = release_dir / "checksums.txt"
-          with checksum_path.open("w", encoding="utf-8") as file:
-              for asset in assets:
-                  file.write(f"{sha256(asset)}  {asset.name}\n")
-          PY
+          PLATFORM_MATRIX: ${{ needs.release-info.outputs.platform_matrix }}
+        run: ruby .github/scripts/package-release.rb archives
 
       - name: Generate release asset provenance
         uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
@@ -404,16 +280,18 @@ jobs:
           subject-path: dist/release/*
 
       - name: Upload release assets
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: release-assets
           path: dist/release
           if-no-files-found: error
-          retention-days: 1
+          retention-days: 7
+          # tar.gz 已压缩，Actions 只负责传递原始发行字节。
+          compression-level: 0
 
   build-docker-image:
     name: build-docker-image (${{ matrix.dockerPlatform }})
-    needs: [release-info, quality, build-docker-binary]
+    needs: [release-info, frontend, build-docker-binary]
     strategy:
       fail-fast: false
       matrix: ${{ fromJson(needs.release-info.outputs.docker_matrix) }}
@@ -435,48 +313,36 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download frontend artifact
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: frontend-dist
           path: dist/docker/web/dist
 
       - name: Download Docker binary artifacts
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/docker-artifacts/codex-proxy-rs-${{ matrix.os }}-${{ matrix.arch }}
 
+      - name: Download sealed plugin assets
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: plugin-release-assets
+          path: dist/plugin-release-assets
+
       - name: Prepare Docker prebuilt assets
         shell: bash
         env:
           MATRIX_OS: ${{ matrix.os }}
           MATRIX_ARCH: ${{ matrix.arch }}
           MATRIX_BINARY: ${{ matrix.binary }}
-        run: |
-          set -euo pipefail
-          python3 - <<'PY'
-          import shutil
-          import os
-          import pathlib
-
-          app_name = "codex-proxy-rs"
-          platform_name = f"{os.environ['MATRIX_OS']}-{os.environ['MATRIX_ARCH']}"
-          binary_src = pathlib.Path("dist/docker-artifacts") / f"{app_name}-{platform_name}" / os.environ["MATRIX_BINARY"]
-          if not binary_src.is_file():
-              raise SystemExit(f"Missing Docker binary artifact: {binary_src}")
-
-          target_dir = pathlib.Path("dist/docker") / platform_name
-          target_dir.mkdir(parents=True, exist_ok=True)
-          binary_dest = target_dir / app_name
-          shutil.copy2(binary_src, binary_dest)
-          binary_dest.chmod(0o755)
-          PY
+        run: ruby .github/scripts/package-release.rb image
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Login to GHCR
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -484,7 +350,7 @@ jobs:
 
       - name: Build and push app image
         id: build-and-push
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7.3.0
+        uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0
         with:
           context: .
           file: deploy/Dockerfile
@@ -526,16 +392,20 @@ jobs:
           printf '%s\n' "$IMAGE_DIGEST" > "dist/digests/linux-${IMAGE_ARCH}.txt"
 
       - name: Upload verified image digest
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: image-digest-${{ matrix.os }}-${{ matrix.arch }}
           path: dist/digests/*.txt
           if-no-files-found: error
-          retention-days: 1
+          retention-days: 7
 
   publish:
-    needs: [release-info, package-assets, build-docker-image]
-    runs-on: ubuntu-latest
+    concurrency:
+      group: release-publication
+      queue: max
+    # 产物准备可与测试重叠，版本标签和 GitHub Release 必须等全部质量与镜像验证通过
+    needs: [release-info, quality, windows, security, package-assets, build-docker-image]
+    runs-on: ubuntu-26.04
     timeout-minutes: 20
     permissions:
       contents: write
@@ -550,39 +420,37 @@ jobs:
           ref: ${{ needs.release-info.outputs.git_sha }}
 
       - name: Download release assets
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: release-assets
           path: dist/release
 
       - name: Download verified image digests
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           pattern: image-digest-*
           path: dist/digests
           merge-multiple: true
 
       - name: Setup Docker Buildx
-        uses: docker/setup-buildx-action@37fe631027851001ddb9b187196cc803df7f5f0e # v4.3.0
+        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1
 
       - name: Install Cosign
         uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
 
       - name: Login to GHCR
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
+        uses: docker/login-action@81c6f93d4bc991e510b342a00b419b3bb4efc5c6 # v4.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Create app image manifest
+      - name: Assemble candidate image manifest
         id: manifest
         shell: bash
         env:
-          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
           GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
           DOCKER_PLATFORMS: ${{ needs.release-info.outputs.docker_platforms }}
-          PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
         run: |
           set -euo pipefail
 
@@ -606,16 +474,10 @@ jobs:
             exit 1
           fi
 
-          target_args=(
-            -t "${image}:${DOCKER_VERSION}"
-            -t "${image}:sha-${GIT_SHA}"
-          )
-          if [ "$PRERELEASE" != true ]; then
-            target_args+=(-t "${image}:latest")
-          fi
-          docker buildx imagetools create "${target_args[@]}" "${sources[@]}"
+          candidate="${image}:sha-${GIT_SHA}"
+          docker buildx imagetools create -t "$candidate" "${sources[@]}"
 
-          inspect_output="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}")"
+          inspect_output="$(docker buildx imagetools inspect "$candidate")"
           platform_list="$(awk '$1 == "Platform:" { print $2 }' <<< "${inspect_output}")"
           for platform in "${platforms[@]}"; do
             if ! grep -Eq "^${platform}(/|$)" <<< "${platform_list}"; then
@@ -625,7 +487,7 @@ jobs:
             fi
           done
 
-          digest="$(docker buildx imagetools inspect "${image}:${DOCKER_VERSION}" --format '{{ .Manifest.Digest }}')"
+          digest="$(docker buildx imagetools inspect "$candidate" --format '{{ .Manifest.Digest }}')"
           if [ -z "${digest}" ]; then
             echo "missing image digest"
             exit 1
@@ -639,39 +501,15 @@ jobs:
           subject-digest: ${{ steps.manifest.outputs.digest }}
           push-to-registry: true
 
-      - name: Sign app image
-        shell: bash
+      - name: Sign app image digest
         env:
           DIGEST: ${{ steps.manifest.outputs.digest }}
-          DOCKER_VERSION: ${{ needs.release-info.outputs.docker_version }}
-          GIT_SHA: ${{ needs.release-info.outputs.git_sha }}
-          PRERELEASE: ${{ needs.release-info.outputs.prerelease }}
-        run: |
-          set -euo pipefail
-          if [ -z "${DIGEST}" ]; then
-            echo "missing image digest"
-            exit 1
-          fi
-
-          image="${REGISTRY}/${IMAGE_NAME}"
-          tags=("${image}:${DOCKER_VERSION}" "${image}:sha-${GIT_SHA}")
-          if [ "$PRERELEASE" != true ]; then
-            tags+=("${image}:latest")
-          fi
-          images=()
-          for tag in "${tags[@]}"; do
-            images+=("${tag}@${DIGEST}")
-          done
-
-          cosign sign --yes "${images[@]}"
+        run: cosign sign --yes "${REGISTRY}/${IMAGE_NAME}@${DIGEST}"
 
       - name: Prepare release notes
         shell: bash
         env:
           INSTALLATION_NOTES: |
-            > [!WARNING]
-            > **跨大版本升级：** 不支持跨大版本在线升级。请使用全新的 `.runtime/` 数据目录重新部署，再重新导入或重新授权服务商账号，并重新导入客户端密钥。详见[升级说明](https://github.com/${{ github.repository }}/blob/${{ needs.release-info.outputs.tag }}/deploy/README.md#镜像升级与源码构建)。
-
             ## 📥 安装
 
             **Docker 部署：**
@@ -685,6 +523,9 @@ jobs:
             **手动下载：**
             请从下方附件中下载适合当前平台的归档包。
 
+            附件包含与当前宿主版本及提交绑定的 `plugin-release-manifest.json`，当前没有默认内置插件。
+            教学示例由独立的 `codex-proxy-plugins` 仓库维护和发布，不随宿主发行物分发。
+
             发布归档提供 GitHub 构建产物证明。Docker 镜像附带软件物料清单（SBOM）、构建来源证明和 cosign 无密钥签名。
 
             ## 📚 文档
@@ -692,25 +533,33 @@ jobs:
             - [GitHub 仓库](https://github.com/${{ github.repository }})
             - [部署指南](https://github.com/${{ github.repository }}/blob/${{ needs.release-info.outputs.tag }}/deploy/README.md)
         run: |
-          python3 <<'PY'
-          import os
-          from pathlib import Path
+          ruby <<'RUBY'
+          notes = File.readlines('release/notes.md').drop(1).join.strip
+          installation = ENV.fetch('INSTALLATION_NOTES').strip
+          output = File.join(ENV.fetch('RUNNER_TEMP'), 'release-notes.md')
+          File.write(output, "#{notes}\n\n#{installation}\n")
+          RUBY
 
-          notes = "\n".join(Path("release/notes.md").read_text().splitlines()[1:]).strip()
-          installation = os.environ["INSTALLATION_NOTES"].strip()
-          output = Path(os.environ["RUNNER_TEMP"]) / "release-notes.md"
-          output.write_text(f"{notes}\n\n{installation}\n")
-          PY
-
-      - name: Publish GitHub Release
+      - name: Upload GitHub Release assets
+        id: release
         uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
         with:
           tag_name: ${{ needs.release-info.outputs.tag }}
           generate_release_notes: true
           previous_tag: ${{ needs.release-info.outputs.previous_tag }}
           prerelease: ${{ needs.release-info.outputs.prerelease == 'true' }}
-          make_latest: ${{ needs.release-info.outputs.prerelease == 'true' && 'false' || 'true' }}
+          # action 保留已公开 Release 的状态，新 Release 上传完成后仍保持草稿
+          draft: true
+          make_latest: 'false'
           body_path: ${{ runner.temp }}/release-notes.md
           fail_on_unmatched_files: true
           files: |
             dist/release/*
+
+      - name: Publish version and advance latest
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          VERSION: ${{ needs.release-info.outputs.version }}
+          DIGEST: ${{ steps.manifest.outputs.digest }}
+          RELEASE_ID: ${{ steps.release.outputs.id }}
+        run: ruby .github/scripts/publish-release.rb

.github/workflows/rules.yml

@@ -0,0 +1,91 @@
+name: Rules Guard
+
+on:
+  pull_request_target:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: rules-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  guard:
+    runs-on: ubuntu-26.04
+    timeout-minutes: 5
+    steps:
+      # 只查询 PR 元数据，禁止检出或执行贡献分支中的代码。
+      - name: Check protected files
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const pr = context.payload.pull_request;
+            const params = { owner, repo, pull_number: pr.number };
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              ...params,
+              per_page: 100,
+            });
+            // 按 PR 作者识别官方机器人，维护者重开或编辑 PR 时仍使用同一判断
+            const isDependabot = pr.user.login === 'dependabot[bot]'
+              && pr.user.type === 'Bot'
+              && pr.head.repo?.full_name === `${owner}/${repo}`;
+            const isDependencyUpdate = file => isDependabot
+              && file.status === 'modified'
+              && (/^\.github\/workflows\/[^/]+\.ya?ml$/.test(file.filename)
+                || /^\.github\/actions\/.+\/(?:action\.ya?ml|Dockerfile)$/.test(file.filename));
+            const isProtectedRule = path => typeof path === 'string'
+              && (path === 'AGENTS.md' || path.endsWith('/AGENTS.md')
+                || path === 'CONTRIBUTING.md'
+                || path === '.agents/skills' || path.startsWith('.agents/skills/')
+                || path === '.github' || path.startsWith('.github/'));
+
+            // 依赖更新只豁免已有文件的修改，重命名前后的受保护路径仍参与检查
+            if (!files.some(file => !isDependencyUpdate(file)
+              && (isProtectedRule(file.filename) || isProtectedRule(file.previous_filename)))) {
+              core.info('No protected contribution rule changes detected.');
+              return;
+            }
+
+            // 旧事件不处理后续提交，也不重复处理已关闭的 PR。
+            const { data: current } = await github.rest.pulls.get(params);
+            if (current.state !== 'open' || current.head.sha !== pr.head.sha) {
+              core.info('Pull request state has changed; skipping this event.');
+              return;
+            }
+
+            // 通知标记保持稳定，以便复用机器人已有评论，避免重复提醒
+            const marker = '<!-- agents-md-guard -->';
+            const body = [
+              marker,
+              '我看到这个 PR 涉及受保护的协作规则文件，按仓库约定需要先关闭',
+              '',
+              '保护范围包括根目录或子目录的 `AGENTS.md`、根目录的 `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 notification = comments.find(comment => comment.user?.login === 'github-actions[bot]'
+                && comment.body?.includes(marker));
+              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 protected contribution rules (AGENTS.md, CONTRIBUTING.md, .agents/skills/, .github/).');

.github/workflows/security-scan.yml

@@ -1,88 +0,0 @@
-name: Security Scan
-
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  schedule:
-    - cron: '0 3 * * 1'
-
-permissions:
-  contents: read
-
-concurrency:
-  group: security-scan-${{ github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.head_ref || github.ref_name }}
-  cancel-in-progress: true
-
-jobs:
-  backend-security:
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        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
-
-      - name: Run cargo audit
-        working-directory: backend
-        shell: bash
-        run: |
-          # 临时接受此中危风险以保持 Codex 0.154.0 的 TLS 指纹；直接升级会新增 ML-DSA 签名算法。
-          # 仅豁免本条公告，2026-09-21 UTC 起恢复阻断；兼容升级验证完成后应提前删除豁免。
-          # https://github.com/rustls/rustls/security/advisories/GHSA-2mjx-qc3c-rqvc
-          audit_advisory_args=()
-          if [[ "$(date -u +%F)" < "2026-09-21" ]]; then
-            audit_advisory_args+=(--ignore RUSTSEC-2026-0285)
-          fi
-          cargo audit "${audit_advisory_args[@]}"
-
-  frontend-security:
-    runs-on: ubuntu-latest
-    timeout-minutes: 15
-    steps:
-      - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-        with:
-          ref: ${{ github.event.pull_request.head.sha || github.sha }}
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
-        with:
-          version: 11.7.0
-
-      - 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: Run pnpm audit
-        run: pnpm --dir frontend audit --prod --audit-level=high
-
-  container-security:
-    if: github.event_name == 'schedule'
-    permissions:
-      contents: read
-      security-events: write
-    uses: ./.github/workflows/_container.yml
-    with:
-      ref: ${{ github.sha }}

.github/workflows/security.yml

@@ -0,0 +1,84 @@
+name: Security
+
+on:
+  workflow_call:
+    inputs:
+      ref:
+        description: Exact commit SHA to audit
+        required: true
+        type: string
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: '0 3 * * 1'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ inputs.ref || github.event.pull_request.head.repo.full_name || github.repository }}-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  backend-security:
+    runs-on: ubuntu-26.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.event.pull_request.head.sha || github.sha }}
+
+      - name: Install cargo-audit
+        uses: taiki-e/install-action@682ce6c3c696a4cd5168a05f98e51aa02b877941 # v2.89.1
+        with:
+          tool: cargo-audit@0.22.2
+          fallback: none
+
+      - name: Run Cargo audits
+        run: |
+          cargo-audit audit --file backend/Cargo.lock
+
+  frontend-security:
+    runs-on: ubuntu-26.04
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.ref || github.event.pull_request.head.sha || github.sha }}
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
+        with:
+          package_json_file: frontend/package.json
+
+      - name: Read build toolchains
+        id: toolchains
+        run: ruby .github/scripts/toolchains.rb >> "$GITHUB_OUTPUT"
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: ${{ steps.toolchains.outputs.node }}
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+
+      - name: Install frontend dependencies
+        run: pnpm --dir frontend install --frozen-lockfile
+
+      - name: Run pnpm audit
+        run: pnpm --dir frontend audit --prod --audit-level=high
+
+  container-security:
+    if: github.event_name == 'schedule'
+    permissions:
+      contents: read
+      security-events: write
+    uses: ./.github/workflows/_container.yml
+    with:
+      ref: ${{ github.sha }}

.gitignore

@@ -6,9 +6,8 @@
 # Frontend
 /frontend/node_modules/
 /frontend/dist/
-/frontend/.vite/
-/.pnpm-store/
 /frontend/.pnpm-store/
+/frontend/.pnpm-cache/
 *.tsbuildinfo
 
 # Release artifacts
@@ -20,6 +19,9 @@
 
 # Local configuration and secrets
 /deploy/config.yaml
+.env
+.env.*
+!.env.example
 
 # Editors and operating systems
 /.idea/
@@ -32,6 +34,7 @@ Thumbs.db
 
 # Local tools and worktrees
 /.codegraph/
+/.playwright-cli/
 /.codex-ws-audit/
 /.reasonix/
 /.claude

.gitmodules

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

AGENTS.md

@@ -1,14 +1,34 @@
 # 项目协作约定
 
-开发和审查先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，使用其中的协作流程和审查标准。
+按用户意图和当前会话主动加载并执行仓库技能，不要求用户写出 `$技能名`：
+
+| 任务意图与常见说法 | 必用技能 |
+| --- | --- |
+| 开发、修复、排障、代码审查、改文档；包括“改弹窗／样式／文案”“修接口／调度／数据库”等省略请求 | [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md)，按实际操作和文件匹配规范，跨前后端同时执行 |
+| 提交／提个 PR、准备或更新 PR、看下 PR、回复 PR 讨论、处理 PR 审查意见 | [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md)；实现自审、审查或修改同时执行 cpr-dev-guide |
+| 提 Issue、反馈到仓库、把问题或建议整理成 Issue、补充或回复 Issue | [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) |
+| 写、修或审查独立网关插件，排查插件接入、打包插件 | [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md)，同时执行 cpr-dev-guide；仅改宿主能力时由 cpr-dev-guide 加载插件边界 |
+| 发版、准备版本、发布 beta／实验版、整理发布说明、打发行 tag | [cpr-release](.agents/skills/cpr-release/SKILL.md) |
+
+结合上下文识别“提交吧”“看看这个问题”等省略说法：普通 Git 提交不自动变成 PR，代码排查不自动变成 Issue；审查与发版准备不代表获准远程写入
+
+先完整读取命中技能的 `SKILL.md`，再读取其领域必读规范，之后按当前步骤补充实现、命令和示例。技能名称、描述或入口摘要不能代替正文与必读引用；引用中明确要求“先读”“必须读取”或“执行”的规范也要落实，其他资料按需读取
+
+按用户意图、行为影响和实际文件共同匹配，跨领域叠加；确定方案或给出审查结论前完成对应领域必读，不能因改动小、路径未落在该模块或自认为熟悉而跳过。只复用当前上下文中已实际读取且仍适用的内容；输出截断、上下文压缩后缺失的必要内容须补读，范围或阶段变化时重新匹配
+
+执行所选流程中的问题核实、自审、验证与交付要求，协作流程和审查标准见 [CONTRIBUTING.md](CONTRIBUTING.md)
+
+Issue 和 PR 回复统一按 [GitHub 回复口吻](CONTRIBUTING.md#github-回复口吻)执行
+
 模块职责以 [系统架构](docs/architecture.md) 为准，界面约定以 [管理端主题](docs/theme.md) 为准；
-没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则。
+没有明确约定时保持与相邻实现一致，不把单次页面反馈扩展成全仓规则
 
 <!-- CODEGRAPH_START -->
 ## CodeGraph
 
 In repositories indexed by CodeGraph (a `.codegraph/` directory exists at the repo root), reach for it BEFORE grep/find or reading files when you need to understand or locate code:
 
+- **Index freshness**: Run `codegraph sync` from the repository root before the first code query in a task. After pulling updates, switching branches, or changing code, run it again before the next query so symbols and call paths match the working tree. If synchronization fails, report the failure and verify against current source rather than treating the index as current.
 - **MCP tools** (when available): `codegraph_explore` answers most code questions in one call — the relevant symbols' verbatim source plus the call paths between them. `codegraph_node` returns one symbol's source + callers, or reads a whole file with line numbers. If the tools are listed but deferred, load them by name via tool search.
 - **Shell** (always works): `codegraph explore "<symbol names or question>"` and `codegraph node <symbol-or-file>` print the same output.
 
@@ -17,27 +37,31 @@ If there is no `.codegraph/` directory, skip CodeGraph entirely — indexing is
 
 ## 工作方式
 
-- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题，以官方源码为首要参考确定或评估方案。
+- 开发和审查按 [问题与方案依据](CONTRIBUTING.md#问题与方案依据) 先核实问题及方案必要性；涉及 Codex 行为、协议或兼容性时，以官方对应版本源码为第一手资料，三方仓库仅作参考
 - 先定位变更所属模块、同类实现和上下游调用关系，再选择最小合理改动。复用已有能力，也避免为尚不存在的需求增加抽象。
+- 提交前自审最终差异，先处理本次引入的职责混淆、重复规则、冗余状态和无依据的兼容分支；后端按 [后端自审](docs/architecture.md#后端自审) 追踪状态与资源生命周期，不能把自审留给 CI 或 PR 审查者。
+- 前端开发与审查执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，先复用已有页面设计与组件，不因个人偏好重排页面或另建交互；页面 PR 必须提供 [实际截图](CONTRIBUTING.md#界面验证)。
 - 代码注释使用中文，解释原因与边界；提交信息使用英文，沿用历史中的 Conventional Commits 格式。
+- 常规文档只描述当前状态，不记录变更历史；按[文档职责与更新条件](CONTRIBUTING.md#文档职责与更新条件)在所属章节就地修订，分清层次与详略，短段和列表少用句号，交付前逐段检查必要性、归属、重复与当前状态表达
 - 按变更范围执行验证，记录命令、结果和缺口。跳过的测试不算通过；界面与集成行为需要对应运行证据，构建通过不能替代实际验收。
 - 审查请求默认只读。修复、提交、推送和合并按用户当前授权执行；“本地验证通过”不等于用户已经审阅批准。
 - 不读取或输出无关凭据，不把真实密钥、代理认证、账号令牌或请求转储放入提交、截图及审查报告。
+- 使用 AI 的 PR 按 [AI 使用披露](CONTRIBUTING.md#ai-使用披露) 写明实际模型型号，不以工具名称代替模型。
 
 ## Code Review Rules
 
 ### 审查范围
 
 - 确认目标分支与当前变更范围，结合调用方、被调用方及已有测试审查；结论对应实际审查的提交或工作区状态。
-- 按 CONTRIBUTING.md 的维度检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称。
+- 按[审查标准](CONTRIBUTING.md#审查标准)检查设计、正确性、安全、复杂度、性能、可读性、验证、界面和文档，深度与变更风险相称
 - 重点核对现有架构和数据合同：共享业务事实是否重复解释，异步与并发操作是否破坏状态，权限和敏感数据是否越界，协议适配是否影响兼容性。
 - 修改既有特殊分支时先查场景和历史；放宽检查、修改测试或新增例外需要业务依据，不能仅以让检查通过为理由。
 
 ### 代码与界面一致性
 
 - 对重复逻辑、冗余状态和多余抽象给出具体位置及影响；建议复用时指出已有实现，不能仅凭行数或语法相似判定质量。
-- UI 变更对照项目基础组件、主题和同类页面，检查交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。
-- 核对截图、预览和实际交互证据；未检查的状态明确列为验证缺口，不推断视觉验收已经通过。
+- UI 变更对照原页面、项目基础组件、主题和同类页面，检查布局变化是否服务本次需求、是否堆叠重复文案，以及交互、状态、响应式与可访问性。局部问题是否应在共用组件修复，按职责判断，不一律禁止局部样式。
+- 核对页面 PR 按 [界面验证](CONTRIBUTING.md#界面验证) 提供的截图与实际交互证据；缺少必需截图时明确要求补齐，未检查的状态列为验证缺口，不推断视觉验收已经通过。
 
 ### 审查输出
 

CONTRIBUTING.md

@@ -1,58 +1,105 @@
 # 贡献与审查
 
-贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理。
+贡献应解决明确的问题，并保持或改善项目的可维护性。提交者、自动检查和审查者使用同一套标准，让重复问题在提交和初审阶段得到处理
 
-本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制。
+本文定义协作流程与审查标准；模块职责以 [系统架构](docs/architecture.md) 为准，视觉规则以 [管理端主题](docs/theme.md) 为准。没有明确约定时遵循相邻实现；具体页面的布局决定不自动成为全项目限制
 
-## 提交 Issue
+## 交流与反馈
 
-问题反馈使用仓库的 [Issue 表单](.github/ISSUE_TEMPLATE/bug_report.yml)，填写问题类型、描述、版本与环境、复现步骤和预期结果。接口问题补充平台与认证类型、模型、客户端，以及脱敏后的请求、响应和请求 ID；页面问题附相关截图或录屏。
+[讨论区](https://github.com/zyycn/codex-proxy-rs/discussions) 用于使用问答、想法讨论、实验反馈和经验分享。
+提问时按需补充版本、部署方式、已尝试的方法及脱敏信息；问题解决后，请在「使用问答」中标记有帮助的答案
 
-日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议与协作规则调整可直接提交 Issue，说明场景、原因和建议方案。
+明确的 Bug、具体功能需求或协作规则建议使用 Issue，无需先开讨论。
+讨论形成可执行事项后，可以新建 Issue 并互相附链接；已有 Issue 的后续信息继续补充在原帖，避免重复记录。
+围绕问题友善交流，欢迎不同使用场景和方案观点
+
+### 提交 Issue
+
+按场景选择 [接口问题反馈](.github/ISSUE_TEMPLATE/api-bug-report.yml)、[常规问题反馈](.github/ISSUE_TEMPLATE/general-bug-report.yml) 或 [功能建议](.github/ISSUE_TEMPLATE/feature-request.yml) 表单，按对应提示提供信息。故障反馈填写实际运行版本和中转链路；接口问题区分客户端显示与网关实际响应，页面问题附相关截图或录屏
+
+日志和配置只提供定位所需片段，不上传真实凭据或完整请求转储。功能建议说明使用场景、当前不便和期望行为；协作规则调整可直接提交普通 Issue，说明原因和建议方案
+
+### GitHub 回复口吻
+
+AI 草拟、发布或修改 Issue、PR 讨论及审查意见的回复时，以一起排查问题、讨论方案的口吻交流：
+
+- 围绕问题、事实和结论展开，能自然省略主语时省略；需要说明个人判断或行动归属时用“我”，避免反复以“我”起句或强调自己，不用“我们”“本助手”代称自己
+- 普通回复直接回应问题，不加问候语或称呼；向对方提问时称呼“佬”，同一条回复不重复称呼
+- 先接住对方想完成的事和遇到的困难，再给出核实结果与建议；回复让对方感到问题被理解、有下一步可做，避免一上来归类、纠正或划定责任
+- 给出操作建议时说明它能帮助判断什么，措辞自然、委婉，不靠堆叠缓和词修饰命令
+- 回应已有能力、暂不支持或未采纳的建议时，结合场景说明可用入口或具体原因，有可行替代办法时一并说明，再交代必要边界；避免只回复“已有功能”“重复问题”“不在范围内”等结论
+- 需要补充材料或配合操作时，先利用已有信息，只询问仍缺少的部分，说明用途和最小范围；例如“佬，方便再观察几次吗？如果还出现，可以附一下对应请求的诊断包，便于对照终态用量”
+- 澄清误解或提出不同意见时，从观察和依据说起，照顾对方的使用环境与理解路径，避免责备、反问或居高临下的判断；已确认的事实保持明确，尚未确认的原因保留余地
+- 使用自然短句，简单回复用短段，并列信息较多时再分点；少用句号，避免客服套话、机械模板和空泛保证
+- 排查、复现、修改和验证的完成状态与实际一致；未采纳的意见说明依据，未确认、待处理或未验证的内容如实交代，说清结论、限制和下一步
 
 ## 问题与方案依据
 
-开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题。
+开发、创建 PR 和审查都先核实待解决的问题、触发条件与预期行为，再确定或评估实现。区分问题发生版本、目标分支现状和本次变更后的行为，不把需求描述、PR 描述或第三方项目的做法直接当成事实。目标分支已修复的问题，应说明当前仍需补齐的差异，不能据此否定旧版本中的问题
 
-涉及上游协议、客户端行为或兼容性时，以对应版本的官方源码为首要资料。优先读取用户提供或本机已有的官方源码，核对仓库来源、版本或提交；本地资料不足时查官方仓库的对应版本源码，再结合官方测试、文档、发布说明和运行证据。第三方资料只作线索或补充。引用具体文件、符号或行号，对外引用优先使用固定提交的源码链接；源码不可得或版本不匹配时说明证据缺口，不把最新实现当成当前部署行为。无上游依赖的内部变更，以本项目代码、合同和运行证据为依据。
+涉及上游协议、客户端行为或兼容性时，遵守以下依据与行为约束；无上游依赖的内部变更以本项目代码、合同和运行证据为依据
 
-官方已有同一场景的处理方式时，优先沿用其协议语义、职责归属和解决路径，检查是否只需复用已有能力或正确传递官方合同。新增覆盖配置、补偿逻辑或采用第三方兼容方案，应说明官方路径为何不足；偏离官方方案需有本项目的实际约束和验证依据，不机械照搬源码，也不默认接受已有提案。
+- **资料来源**：以对应版本的官方源码与调用链为首要资料，Codex 对照 [openai/codex](https://github.com/openai/codex)。先查用户提供或本机已有的仓库，核对来源、版本或提交；不足时再查官方对应版本源码，结合测试、文档、发布说明和运行证据。三方资料只作线索或实现参考，不能替代官方依据
+- **证据表达**：引用具体文件、符号或行号，对外优先使用固定提交的源码链接；注明适用版本，区分官方事实、三方参考与本项目推断。源码不可得或版本不匹配时报告缺口，不把最新实现当作部署行为，也不把自定义策略写成官方要求
+- **默认方案**：Codex 兼容性优先保持官方行为，以透明转发和最小必要适配为默认方案。沿用官方协议语义、职责归属和解决路径，优先复用已有能力或正确传递合同，不额外解释请求意图、扩展工具权限或改变续接语义
+- **问题核实**：对照官方与 CPR 的实际请求、响应及状态生命周期，检查本项目是否误解、改写、遗漏或破坏合同；分别说明源码推断、代理链路复现与官方直连结果。真实上游报错不自动等于 CPR 缺陷
+- **审查官方对接**：审查 OpenAI 官方上游与 Codex 的对接时，默认二者兼容、直接对接正常。不得仅凭自行构造的异常上游数据揣测官方不兼容，据此报告缺陷、提出改进建议或要求防御分支与测试；特定版本或场景的例外须有真实响应或实际复现证据
+- **偏离依据**：新增覆盖配置、补偿逻辑或三方兼容方案前，说明官方路径为何不足、本项目实际约束、最小改动、行为代价及验证。补偿后成功、测试通过或三方采用同一做法不能单独证明必要性；依据不足时保持现有合同并报告缺口，不先加分支再倒推理由。用户明确要求的行为变更限定在授权范围内
+- **网关职责**：调度、隔离和资源管理按网关职责评估，不机械照搬单客户端实现，不因官方客户端没有同类池策略就判错，也不任意改变客户端可观察行为。新增默认限制或回收阈值须有容量依据，并验证续接、重试与延迟影响
 
-反馈 Issue 时区分观察到的症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。能说明问题的反馈可以先提交，不要求报告者先找到官方源码或证明根因；引用官方行为或提出实现方案时，按上述原则注明依据与缺口。
+反馈 Issue 时区分症状、根因假设和方案建议，关联已有 Issue、PR 及包含修复的发布版本。症状反馈不以找到官方源码或证明根因为前提；引用上游行为或提出方案时注明上述依据与缺口
 
 ## PR 流程
 
-1. **准备变更。** 按上述依据核实问题与方案，找到所属模块、相关调用链和最接近的现有实现，在功能分支完成修改与自查。涉及架构、公开合同或较大交互变化时，先说明方案与取舍。
-2. **发起 PR。** 目标分支使用 `main`。说明问题成立的依据、触发场景、改动后的行为和实际验证结果；涉及官方行为时注明源码位置、版本和方案关系。界面改动提供截图、录屏或可复现的预览方式。一个 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 正文代替实现自审与验证
 
 | 技能 | 用途 | 调用示例 |
 | --- | --- | --- |
-| [dev-guide](.agents/skills/dev-guide/SKILL.md) | 项目开发与文档导航 | `$dev-guide 修复当前问题` |
-| [github-pr](.agents/skills/github-pr/SKILL.md) | 创建或审查 PR | `$github-pr 创建当前分支的 PR` / `$github-pr 审查 PR #编号` |
-| [github-issue](.agents/skills/github-issue/SKILL.md) | 整理或提交 Issue | `$github-issue 提交当前问题` |
-| [release](.agents/skills/release/SKILL.md) | 准备发布说明或正式发版 | `$release 整理本次发布说明` / `$release 发布 vX.Y.Z` |
+| [cpr-dev-guide](.agents/skills/cpr-dev-guide/SKILL.md) | 项目开发与文档导航 | `$cpr-dev-guide 修复当前问题` |
+| [cpr-plugin-dev](.agents/skills/cpr-plugin-dev/SKILL.md) | 网关插件开发、打包与验证 | `$cpr-plugin-dev 开发一个添加响应头的插件` |
+| [cpr-github-pr](.agents/skills/cpr-github-pr/SKILL.md) | 准备、创建、更新或审查 PR | `$cpr-github-pr 创建当前分支的 PR` / `$cpr-github-pr 审查 PR #编号` |
+| [cpr-github-issue](.agents/skills/cpr-github-issue/SKILL.md) | 整理或提交 Issue | `$cpr-github-issue 提交当前问题` |
+| [cpr-release](.agents/skills/cpr-release/SKILL.md) | 准备发布说明或正式发版 | `$cpr-release 整理本次发布说明` / `$cpr-release 发布 vX.Y.Z` |
 
-审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查。
+审查请求默认在当前会话报告；明确要求创建 PR、提交 Issue 或正式发版时才执行对应远程操作。技能安装不等于启用 GitHub 自动审查
+
+### AI 使用披露
+
+PR 正文说明提交者是否使用 AI。使用 AI 参与方案、代码、文档、测试或自审时，写明工具名称和实际模型型号；使用多个模型时分别列出，可简述各自参与范围。
+`Codex`、`ChatGPT`、`Claude Code` 等工具或产品名称不能代替模型型号，优先填写工具显示或调用配置中的具体模型标识。
+无法获知型号时如实标记「型号未提供，待补充」，不能猜测或伪造，也不能把待补信息称为已完成披露；补齐前保留 Draft。
+更新 PR 时同步新增的模型信息；这一披露不替代提交者自审、验证责任或已有提交署名约定
 
 ### 规则文件保护
 
-PR 不接受根目录或子目录中 `AGENTS.md` 的新增、修改、删除或重命名。调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/agents-md-guard.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查。
+PR 不接受以下协作规则文件的新增、修改、删除或重命名：
 
-源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流。
+- 根目录及任意子目录的 `AGENTS.md`
+- 根目录的 `CONTRIBUTING.md`
+- `.agents/skills/` 中的所有文件，包括技能入口、引用文档、配置和脚本
+- `.github/` 中的所有文件，包括工作流、Actions、Issue／PR 模板和依赖更新配置
+
+官方 `dependabot[bot]` 从本仓库分支发起的依赖更新可修改 `.github/workflows/` 中已有的 YAML 工作流，以及 `.github/actions/` 下已有的 `action.yml`、`action.yaml` 和 `Dockerfile`，继续执行正常审查与 CI；其他受保护文件以及新增、删除、重命名不在例外范围内
+
+除此之外，调整这些文件时先提交 Issue 说明原因和建议，由维护者处理；[规则保护工作流](.github/workflows/rules.yml) 会提示并关闭包含此类变更的 PR。撤销相关变更后可以重新打开 PR，继续正常检查
+
+源码变更遵守现有架构边界与迁移冻结规则，由对应 CI 检查执行；不额外设立整块业务目录的 PR 禁改清单。构建、测试和安全扫描复用现有工作流
 
 ## 审查标准
 
-按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告。
+按改动涉及的范围选择检查深度，无需为每个 PR 填写所有维度的报告
 
-结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证。
+结论先回答原问题是否成立（成立、部分成立、不成立或证据不足），说明触发条件和依据；再判断解决方向是否合理，交代适用的官方方案、本次实现与它的关系及必要调整，最后报告实现问题与验证缺口。原问题是否成立与 PR 实现是否正确分别判断。源码推断、实际复现和检查结果分别说明，CI 通过不能代替问题与方案的论证
 
 | 维度 | 检查重点 |
 | --- | --- |
@@ -68,51 +115,90 @@ 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/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 和准备测试库 | 冻结规则、升级约束和测试环境，不罗列迁移历史 |
+| [共用组件](modules/ui/README.md)及其组件参考 | 如何安装、使用和开发独立 UI 库 | 组件公开 API、主题能力与库内开发；宿主页面约定归管理端主题，跨仓库联调归开发文档 |
+| [官方插件示例](modules/plugins/README.md)及其示例说明 | 如何构建、使用和维护示例插件 | 示例自身的功能、配置与验证；通用协议归 SDK，宿主安装操作归插件使用文档 |
+| [AGENTS.md](AGENTS.md) 与[项目技能](.agents/skills/cpr-dev-guide/SKILL.md) | AI 如何选择并执行任务流程 | 任务匹配、执行步骤和规范入口，不另建模块合同、版本表或协作标准 |
+| 本文 | 如何协作、审查和交付 | 流程、判断标准与验证要求，任务入口由 [开发技能](.agents/skills/cpr-dev-guide/SKILL.md) 串联 |
+
+- 同一事实只在所属文档完整说明，其他位置按读者任务保留必要摘要和链接
+- 改动原因、前后对比、排查经过和验证结果放在 PR、Issue 或任务报告；`release/notes.md` 是发版时使用的发布说明，不作为常规文档的历史章节，也不随普通开发任务自动追加
+- 仍影响升级、恢复或兼容使用的内容，写成明确的适用条件与操作，保留必要限制，不叙述演变过程
+
+### 层次与行文
+
+- 按读者任务组织章节，先给入口和操作，再解释限制；长篇参考文档提供导航，独立主题使用小标题
+- 快速开始只保留走通流程的必要步骤；API、配置、恢复和权限等容易误用的内容写清输入、默认值、边界与失败处理
+- 短说明直接成段，并列信息用列表，可比较的字段或职责用表格，避免一段堆叠多个主题
+- 标题、表格单元格、短列表项和独立短段通常不加句号；长段优先拆分，确需区分完整句意时保留句号，不机械替换成逗号或分号
+- 命令、URL、版本号、字段名和原始输出保持准确，不为统一标点改写代码示例
+
+审查时逐段核对：是否属于当前状态、是否回答读者问题、是否放在正确文档、是否重复、脱离变更背景能否独立理解
+
+没有文档改动本身不构成验证缺口，判断依据是当前说明是否仍然准确、完整
 
 ## 界面验证
 
-AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方案以本项目的用户任务、[管理端主题](docs/theme.md) 和已有组件为依据，在任务范围内改进布局、视觉与交互。
+AI 进行前端开发或审查时，执行[前端流程](.agents/skills/cpr-dev-guide/references/frontend.md)，覆盖页面、组件、弹窗、表单及局部文案和样式。用户指定设计技能时使用该技能；未指定时，只有任务明确需要建立或重塑视觉方向才使用 `$frontend-design`。新增页面也优先沿用 [管理端主题](docs/theme.md) 和已有设计，设计技能不构成重做页面的理由
 
-开发前查找同类页面及 `components/base` 中的基础组件，优先使用已有主题 Token、交互和数据展示逻辑。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题。
+开发前查找原页面、同类页面及 `modules/ui/src/components` 中的基础组件，明确参考实现和可复用部分，再确定最小改动。只有原设计不能满足本次操作或存在具体问题时才调整结构，并在 PR 中说明原因；不顺带换风格、重排无关区域或增加重复的模式入口。需要扩展时在对应职责层修改；局部样式的适用范围遵循主题文档，不一律禁止，也不靠页面覆盖掩盖共用组件的问题
 
-列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令。
+列表列宽、序号、按钮、分页和弹窗尺寸由实际任务与数据规模决定，以同类页面为参照。新增或调整交互时说明用户需要完成什么操作，不把某个页面的取舍推广成全局禁令
 
-提交者在浏览器中验证受影响路径，提供前后截图、录屏或预览步骤，并标明实际覆盖的状态。按变更选择浅色/深色、窄窗口、空/加载/错误状态、大量数据及键盘操作；共用主题或基础组件变更按主题文档扩大验证范围。模拟数据与预览材料不包含真实凭据。
+提交者在浏览器中验证受影响路径，页面变更的 PR 必须提供实际运行截图，包括布局、文案、样式和交互状态的变化：
 
-涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收。
+- 修改现有页面提供变更前后截图，尽量保持相同数据、主题和窗口尺寸；新增页面提供完成态截图。截图保留必要上下文，让审查者能判断布局和信息密度，不只截取孤立控件
+- 按影响范围补充浅色/深色、窄窗口及空/加载/错误等受影响状态；共用主题或基础组件变更按主题文档扩大验证范围。弹出层中的内容需展示展开状态，不能只截关闭后的页面
+- 在 PR 正文嵌入或链接审查者可访问的图片，注明页面入口、状态和对应提交。录屏、预览地址和复现步骤用于补充，不能替代截图；本机绝对路径不算可供远端审阅的附件
+- 视觉或交互继续修改后更新受影响截图，使证据对应待审实现。截图与模拟数据不得包含真实凭据，不用设计稿、生成图片或旧版截图冒充运行结果
+- 环境不足时说明缺少的截图和交互验证，不宣称验收通过；页面 PR 在截图补齐前保留 Draft，不标为可审阅或建议合并
+
+截图用于视觉审阅，保存、切换、错误恢复和键盘操作等行为仍需实际验证并记录覆盖范围，不能仅凭静态图片推断交互正确
+
+当前用户明确接管或确认本轮视觉验收时，沿用约定分工和结果；明确免除本次截图时，该项不再阻塞交付或要求 Draft。报告区分用户确认、AI 实测和未验证，其他验证仍执行；后续修改只复核受影响部分
+
+涉及浏览器能力或访问环境差异时，按项目支持的部署方式核对相关 HTTP/HTTPS、localhost/实际部署地址与浏览器版本，记录实际覆盖的条件；本地预览正常不能替代部署环境中的交互验收
 
 ## 验证
 
-选择与变更相关的检查，纯文档修改无需重建前后端。行为修复补充能覆盖触发条件和结果的测试，不增加仅复述实现的断言。
+按变更风险明确要验证的行为与通过条件，优先复用现有检查；缺少有效回归覆盖时补充行为测试，不为表名、字段清单或 SQL 文本形状单独保留测试，也不增加仅复述实现的断言。纯文档修改无需重建前后端
+
+必要验证通过且没有新改动、失败或未解疑点后停止扩围与重复运行。真实账号验证满足约定场景后即收尾，不无目的重复请求；用户限定验证范围或次数时按其要求执行，未覆盖项如实列出
+
+临时预览、模拟数据、诊断脚本与压测产物放在 `.runtime/` 或系统临时目录，使用后按需清理；只有持续维护的工具和回归测试进入源码目录，不把一次性验收产物混进 `src/`、`examples/` 或正式提交
 
 | 范围 | 现有检查 | 仍需提供的证据 |
 | --- | --- | --- |
@@ -122,6 +208,10 @@ AI 进行前端开发时，加载并使用 `$frontend-design` 技能。设计方
 | 依赖安全 | Cargo Audit、pnpm Audit | 本次变更的权限、数据与信任边界 |
 | 工作流与容器 | Actionlint、相关容器检查 | 改动涉及的运行行为 |
 
+环境准备、依赖安装和服务启动见 [开发与源码联调](docs/development.md)，联合修改组件库或插件时使用其中的子模块入口
+
+正式依赖固定到标签或提交，联调只临时替换解析路径，不改写正式依赖或锁文件
+
 前端从仓库根目录执行：
 
 ```bash
@@ -130,16 +220,24 @@ 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 服务或更改分支设置。
+常规容器检查与发行构建共用二进制构建入口，并复用已检查的前端产物；Dockerfile、工具链、依赖或构建配置变化时执行完整源码镜像构建，定期安全检查也覆盖源码构建。两条路径均验证容器运行、安全扫描与关闭行为
+
+发行构建与质量检查并行，Windows 两种架构的插件与系统更新测试独立运行。仅当发行提交只修改版本与发布说明，且其父提交有本仓库主分支成功的后端 CI 时复用该结果；缺少证据则完整重跑。对外发布等待质量、Windows 测试、依赖审计和镜像验证全部成功，构建耗时与测试报告保留 7 天
+
+新增自动规则优先使用现有工具，要求依据明确、结果稳定、误报可控；无法可靠判定的设计与视觉问题保留审查判断，避免把具体源码写法锁成测试
+
+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 服务或更改分支设置

README.md

@@ -12,89 +12,101 @@
 [![GHCR](https://img.shields.io/badge/GHCR-codex--proxy--rs-2496ED?logo=docker&logoColor=white&style=flat-square)](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
 
-[快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
+[快速预览](#快速预览) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
 
 </div>
 
 > [!NOTE]
-> 本项目提供 Responses API，不支持 `/v1/chat/completions`。接入前请确认客户端支持 Responses 协议。
+> 本项目提供 Responses API 和 Chat Completions API；Chat Completions 请求通过 Responses 链路执行，支持范围见 [API 参考](docs/api.md#chat-completions-请求)
+
+## 快速预览
+
+无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计：
+
+| 登录信息 | 默认值 |
+| --- | --- |
+| 地址 | <https://codex-proxy-rs.ainz.cc> |
+| 登录身份 | 管理员 |
+| 账号 | `admin@cpr.local` |
+| 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |
+
+预览服务运行已发布版本，展示的账号、代理与使用记录均为模拟数据，每天北京时间 `00:00` 自动生成当天数据
+
+这是公开共享的功能预览环境，不提供真实模型调用；请勿导入真实账号、密钥或其他敏感信息
 
 ## 快速开始
 
-使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis。
-以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。已有部署请先看
-[升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置。
+使用 Docker Compose 部署版本固定的发布镜像，同时启动 PostgreSQL 和 Redis
 
-### 1. 下载部署文件并配置
+以下命令适用于 Linux amd64/arm64，需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL
+
+Windows x64 / ARM64 使用发行包部署，步骤见 [Windows 二进制部署](deploy/README.md#windows-二进制部署)
+
+已有部署请先看 [升级说明](deploy/README.md#镜像升级与源码构建)，不要覆盖原配置
+
+### 一键安装
+
+请确保当前用户能访问 Docker，并可通过 `sudo` 或 root 设置目录权限
 
 ```bash
-mkdir -p codex-proxy-rs/deploy && cd codex-proxy-rs
-
-# 只解析一次最新正式版本，确保两个文件来自同一 Release。
-CPR_RELEASE_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' https://github.com/zyycn/codex-proxy-rs/releases/latest)"
-CPR_RELEASE_TAG="${CPR_RELEASE_URL##*/}"
-curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/compose.yaml" \
-  -o deploy/compose.yaml
-curl -fsSL "https://github.com/zyycn/codex-proxy-rs/releases/download/${CPR_RELEASE_TAG}/config.example.yaml" \
-  -o deploy/config.example.yaml
-
-install -d -m 0750 .runtime/postgres .runtime/redis
-sudo install -d -m 0770 -o "$(id -u)" -g 10001 .runtime/data .runtime/logs
-sudo install -m 0640 -o "$(id -u)" -g 10001 deploy/config.example.yaml deploy/config.yaml
+curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/install.sh -o install.sh && bash install.sh
 ```
 
-也可将 `CPR_RELEASE_TAG` 设置为指定的发布标签。Release 附带的 `compose.yaml` 默认使用该版本镜像，
-配置模板和部署文件均包含在 `checksums.txt` 中；不要混用 `main` 分支模板与已发布镜像。
+[安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`，下载同一正式 Release 的部署文件，
+自动生成密码、设置目录权限并启动服务
 
-分别生成数据库和 Redis 密码：
+完成后保存显示的访问地址和管理员密码，再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)
+
+可在执行 `bash install.sh` 时传入环境变量：
+
+| 变量 | 用途 | 默认值 |
+| --- | --- | --- |
+| `INSTALL_DIR` | 安装目录，建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
+| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
+| `ADMIN_PASSWORD` | 管理员初始密码，至少 12 位，不能包含 `$`，不能使用常见弱口令 | 随机生成 |
+
+例如，自定义安装目录：
 
 ```bash
-openssl rand -hex 24
-openssl rand -hex 24
+INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
 ```
 
-编辑 `deploy/config.yaml`，填好以下三项：
+重复运行时请使用同一安装目录，检测到 `deploy/config.yaml` 后，脚本保留现有配置和部署文件，
+忽略传入的管理员密码，也不执行版本升级
 
-| 配置项 | 填写内容 |
-| --- | --- |
-| `store.database.password` | 第一个生成的 48 位十六进制密码 |
-| `store.redis.password` | 第二个生成的 48 位十六进制密码 |
-| `admin.default_password` | 管理员初始密码，至少 12 位，不能包含 `$` |
+### 手动安装
 
-### 2. 启动服务
+自行下载部署文件、配置密码和启动服务的完整步骤见 [部署文档](deploy/README.md#手动安装)
 
-```bash
-docker compose -f deploy/compose.yaml config --quiet
-docker compose -f deploy/compose.yaml pull
-docker compose -f deploy/compose.yaml up -d --no-build --wait
-curl -i http://127.0.0.1:8080/healthz
-```
+### 登录管理端
 
-健康检查返回 `204 No Content` 后，打开 `http://127.0.0.1:8080`，
-使用 `admin@cpr.local` 和刚设置的管理员密码登录。
+部署完成后，打开 `http://127.0.0.1:8080`，使用 `admin@cpr.local` 和管理员密码登录
 
-默认地址只能在服务器本机访问。从其他设备使用时，需要配置
-[HTTPS 反向代理](deploy/README.md#公网访问)。
+API Key 持有者可在登录页切换身份，查看自己的用量与额度，并通过「密钥配置」复制 Codex 配置或导入 CC Switch
 
-### 3. 添加账号与客户端密钥
+默认地址只能在服务器本机访问，从其他设备使用时，需要配置
+[HTTPS 反向代理](deploy/README.md#公网访问)
 
-1. 在「账号」中添加账号，完成授权或导入。
-2. 按需建立账号分组，再创建客户端密钥并选择可用分组。**不选分组表示可使用全部账号**。
-3. 打开密钥的「使用密钥」，复制客户端配置。
+### 添加账号与客户端密钥
+
+1. 在「账号」中添加账号，完成授权或导入
+2. 按需建立账号分组，再创建客户端密钥并选择可用分组，**不选分组表示可使用全部账号**
+3. [连接客户端](#客户端接入)
 
 ## 客户端接入
 
-**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，或通过 CCSwitch 导入。
-合并到客户端配置后重启 Codex。完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)。
+**Codex CLI / 桌面端**：在「使用密钥」中按操作系统复制配置，合并配置后重启 Codex；也可通过「导入到」把服务连接与密钥添加到 CC Switch
 
-**其他 Responses API 客户端**：填写以下信息。
+完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
+
+**其他 Responses / Chat Completions API 客户端**：填写以下信息：
 
 | 配置 | 值 |
 | --- | --- |
 | Base URL | `http://127.0.0.1:8080/v1`；远程接入使用服务器的 HTTPS 地址 |
 | API Key | 管理端创建的客户端密钥 |
 
-可用模型以该密钥查询到的模型列表为准：
+查询该密钥可见的模型目录：
 
 ```bash
 curl http://127.0.0.1:8080/v1/models \
@@ -103,18 +115,22 @@ curl http://127.0.0.1:8080/v1/models \
 
 ## 文档
 
-- [客户端接入与生图](deploy/README.md#客户端配置)
-- [部署、备份与恢复](deploy/README.md)
-- [API 参考](docs/api.md)
-- [系统架构](docs/architecture.md)
-- [管理端主题](docs/theme.md)
-- [数据库迁移](backend/migrations/README.md)
-- [贡献与审查](CONTRIBUTING.md)
+| 任务 | 文档 |
+| --- | --- |
+| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
+| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
+| 使用插件 | [安装、配置与使用](docs/plugins.md) |
+| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) · [官方示例](https://github.com/zyycn/codex-proxy-plugins/blob/main/README.md) |
+| 开发共用组件 | [组件库说明](https://github.com/zyycn/codex-proxy-ui/blob/main/README.md) · [组件参考](https://github.com/zyycn/codex-proxy-ui/blob/main/playground/components/index.md) · [Playground](https://zyycn.github.io/codex-proxy-ui/) |
+| 开发宿主 | [开发与源码联调](docs/development.md) · [系统架构](docs/architecture.md) · [管理端主题](docs/theme.md) · [数据库迁移](backend/migrations/README.md) |
+| 参与协作 | [贡献、审查与验证](CONTRIBUTING.md) |
 
 ## 社区
 
-感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台。
+问题反馈与功能建议请使用 [GitHub Issues](https://github.com/zyycn/codex-proxy-rs/issues)，填写要求见 [贡献说明](CONTRIBUTING.md#提交-issue)
+
+感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台
 
 ## 许可证
 
-本项目基于 [Apache License 2.0](LICENSE) 开源。
+本项目基于 [Apache License 2.0](LICENSE) 开源

backend/Cargo.toml

@@ -1,10 +1,13 @@
 [workspace]
 members = [
     "apps/gateway",
+    "apps/plugin-cli",
     "crates/gateway-admin",
     "crates/gateway-api",
     "crates/gateway-core",
     "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
     "crates/gateway-protocol",
     "crates/gateway-store",
     "crates/providers/openai",
@@ -17,7 +20,7 @@ version = "0.0.0"
 edition = "2024"
 license = "Apache-2.0"
 publish = false
-rust-version = "1.97"
+rust-version = "1.99.1"
 
 [workspace.lints.rust]
 warnings = "deny"
@@ -32,6 +35,24 @@ 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.1"]
+opt-level = 2
+
+[profile.dev.package."miniz_oxide@0.9.1"]
+opt-level = 2
+
+# workspace 的 WebSocket deflate 特性会让 flate2 选用 zlib-rs
+[profile.dev.package.zlib-rs]
+opt-level = 2
+
 [profile.release]
 debug = false
 strip = "symbols"
@@ -40,5 +61,5 @@ codegen-units = 1
 panic = "abort"
 
 [patch.crates-io]
-# Upstream SOCKS IPv6 fix; remove once a release includes hyperium/hyper-util#302.
-hyper-util = { git = "https://github.com/hyperium/hyper-util", rev = "191b1acf0a6b18e807e4abf5a6d4a7c47979ecd6" }
+# 固定上游 BEGIN 取消回滚修复，避免未结束事务复用；见 transact-rs/sqlx#4394
+sqlx = { git = "https://github.com/transact-rs/sqlx", rev = "f1e94ec34dd5f11ad6488a3a8ac7988439a3f757" }

backend/apps/gateway/Cargo.toml

@@ -16,6 +16,7 @@ gateway-admin = { path = "../../crates/gateway-admin" }
 gateway-api = { path = "../../crates/gateway-api" }
 gateway-core = { path = "../../crates/gateway-core" }
 gateway-host = { path = "../../crates/gateway-host" }
+gateway-plugin-runtime = { path = "../../crates/gateway-plugin/runtime" }
 gateway-store = { path = "../../crates/gateway-store" }
 provider-openai = { path = "../../crates/providers/openai" }
 provider-xai = { path = "../../crates/providers/xai" }

backend/apps/gateway/src/bootstrap.rs

@@ -1,136 +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)]
-#[serde(deny_unknown_fields)]
-pub struct GatewayConfig {
-    schema_version: u32,
-    host: HostConfig,
-    store: gateway_store::StoreConfig,
-    admin: gateway_admin::AdminConfig,
-    api: gateway_api::ApiConfig,
-    openai: provider_openai::OpenAiConfig,
-    xai: provider_xai::XaiConfig,
-    #[serde(default, rename = "services")]
-    _compose_services: Option<serde::de::IgnoredAny>,
-}
-
-impl LoadableConfig for GatewayConfig {
-    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.host.resolve_and_validate(source_dir)?;
-        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.api
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("api"))?;
-        self.openai
-            .resolve_and_validate(&runtime_data_dir)
-            .map_err(|_| ConfigError::InvalidField("openai"))?;
-        self.xai
-            .resolve_and_validate(source_dir)
-            .map_err(|_| ConfigError::InvalidField("xai"))?;
-        Ok(())
-    }
-}
-
-/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host。
-pub async fn run() -> Result<(), BootstrapError> {
-    let config = gateway_host::load_config::<GatewayConfig>()?;
-    let GatewayConfig {
-        schema_version: _,
-        host,
-        store,
-        admin,
-        api,
-        openai,
-        xai,
-        _compose_services: _,
-    } = config;
-
-    let host = gateway_host::initialize(host).await?;
-    host.report_startup_ready("Host");
-    let mut store = gateway_store::initialize(store).await?;
-    host.report_startup_ready("Store");
-    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(xai, provider_ports).await?;
-    host.report_startup_ready("xAI Provider");
-    let providers = ProviderRegistry::new([openai.core_provider(), xai.core_provider()])?;
-    let mut core = gateway_core::initialize(store.core_ports(), providers).await?;
-    host.report_startup_ready("Core");
-    let mut admin = gateway_admin::initialize(
-        admin,
-        store.admin_ports(),
-        vec![openai.admin_provider(), xai.admin_provider()],
-        core.snapshot_control(),
-        (
-            core.account_probe(),
-            host.proxy_probe(provider_openai::build_reqwest_client_with_custom_ca),
-        ),
-        host.client_distribution_resolver(),
-        host.system_operations(),
-    )
-    .await?;
-    host.report_startup_ready("Admin");
-
-    let mut probes = store.health_probes();
-    probes.extend(core.health_probes());
-    probes.push(host.logging_health_probe());
-    let api = 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());
-    host.start_workers(plan, store.worker_leader_lease())?;
-    host.report_startup_ready("Workers");
-    host.serve(api.router()).await?;
-    Ok(())
-}
-
-/// 组合根只保留包级错误分类，不展开内部实现或敏感配置。
-#[derive(Debug, thiserror::Error)]
-pub enum BootstrapError {
-    #[error(transparent)]
-    Config(#[from] gateway_host::ConfigError),
-    #[error(transparent)]
-    Host(#[from] gateway_host::HostError),
-    #[error(transparent)]
-    Store(#[from] gateway_store::StoreError),
-    #[error(transparent)]
-    OpenAi(#[from] provider_openai::OpenAiInitializeError),
-    #[error(transparent)]
-    Xai(#[from] provider_xai::XaiInitializeError),
-    #[error(transparent)]
-    Registry(#[from] RegistryError),
-    #[error(transparent)]
-    Core(#[from] gateway_core::CoreError),
-    #[error(transparent)]
-    Admin(#[from] gateway_admin::model::AdminError),
-    #[error(transparent)]
-    Api(#[from] gateway_api::ApiError),
-}

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

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

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

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

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

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

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

@@ -0,0 +1,110 @@
+//! 插件 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>,
+        upstream_info: Arc<dyn gateway_admin::ports::peer::PeerUpstreamService>,
+    ) -> Self {
+        let ports = store.admin_ports();
+        Self {
+            accounts: gateway_admin::initialize_plugin_accounts(
+                providers.clone(),
+                ports.accounts(),
+                snapshot.clone(),
+                Some(upstream_info),
+            ),
+            keys: gateway_admin::initialize_plugin_client_keys(
+                providers,
+                ports.client_keys(),
+                snapshot.clone(),
+            ),
+            resources: gateway_admin::initialize_plugin_resources(
+                ports.plugin_resources(),
+                snapshot,
+            ),
+        }
+    }
+
+    pub(super) fn bind(&self, runtime: &PluginRuntime) -> Result<(), AdminError> {
+        runtime.bind_account_ports(&self.accounts)?;
+        runtime.bind_client_key_ports(&self.keys)?;
+        runtime.bind_resource_ports(&self.resources)
+    }
+}
+
+pub(super) fn service_middleware(
+    snapshots: RuntimeSnapshotHandle,
+    runtime: &PluginRuntime,
+) -> gateway_admin::public_service::PlanSource {
+    let middleware = runtime.execution_registry();
+    Arc::new(move || {
+        let snapshot = snapshots.snapshot_for_diagnostics()?;
+        middleware.middleware(snapshot.extensions()?)
+    })
+}
+
+pub(super) fn prepare_plugins(
+    store: &gateway_store::StoreBundle,
+    plugin_cache: std::path::PathBuf,
+    version: &str,
+    http: Arc<gateway_host::outbound::HttpClient>,
+) -> Result<Arc<gateway_plugin_runtime::PluginRuntime>, BootstrapError> {
+    Ok(Arc::new(
+        gateway_plugin_runtime::PluginRuntime::new(
+            store.admin_ports().plugins(),
+            store.admin_ports().plugin_state(),
+            gateway_plugin_runtime::PluginRuntimeConfig {
+                cache_directory: plugin_cache,
+                host_version: version
+                    .trim_start_matches('v')
+                    .parse()
+                    .map_err(|_| ConfigError::InvalidField("host.version"))?,
+                package_limits: gateway_plugin_runtime::PackageLimits::default(),
+                rpc_limits: gateway_plugin_runtime::RpcLimits::default(),
+                restart_circuit: Default::default(),
+            },
+            http,
+            Arc::new(gateway_host::process::ProcessSupervisor::default()),
+        )
+        .with_oauth_pending(store.provider_ports().oauth_pending()),
+    ))
+}

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

@@ -0,0 +1,191 @@
+//! 服务模式完成全部组装后交给 Host 监听，并在停止监听与 Worker 收尾后关闭插件
+
+use gateway_host::ConfigError;
+
+use super::{
+    BootstrapError, GatewayConfig,
+    plugins::{ManagementPorts, or_shutdown, prepare_plugins, service_middleware},
+    startup::{Environment, Mode, Providers},
+};
+
+/// 按冻结顺序初始化全部 Bundle，并把进程阻塞权交给 Host
+pub async fn run() -> Result<(), BootstrapError> {
+    let config = gateway_host::load_config::<GatewayConfig>()?;
+    let environment = Environment::initialize(config.host, config.store, Mode::Server).await?;
+    let mut providers = Providers::initialize(config.openai, &environment).await?;
+    let Environment {
+        host,
+        mut store,
+        timezone,
+        plugin_cache,
+        version,
+        plugin_http,
+    } = environment;
+    let plugin_runtime = prepare_plugins(&store, plugin_cache, &version, plugin_http.clone())?;
+    let core = gateway_core::prepare(
+        store.core_ports(),
+        providers.core,
+        Some(plugin_runtime.clone()),
+        Some(plugin_runtime.observer_registry()),
+        Some(plugin_runtime.policy_registry()),
+        Some(plugin_runtime.execution_registry()),
+        Some(plugin_runtime.frontend_authentication_registry()),
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_snapshots(&core.snapshots())
+    );
+    let management = ManagementPorts::new(
+        &store,
+        providers.admin.clone(),
+        core.snapshot_control(),
+        providers.peer.service(),
+    );
+    or_shutdown!(plugin_runtime, management.bind(&plugin_runtime));
+    let mut core = or_shutdown!(plugin_runtime, core.activate().await);
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_client_identity_port(&core.client_identity_port())
+    );
+    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 {
+                upstream_info: Some(providers.peer.service()),
+                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())
+    );
+    or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.bind_usage_queries(&admin.services().usage_data())
+    );
+
+    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.extend(providers.peer.take_worker_contributions());
+    plan.push(or_shutdown!(
+        plugin_runtime,
+        plugin_runtime.maintenance_worker(core.snapshots())
+    ));
+    or_shutdown!(
+        plugin_runtime,
+        host.start_workers(plan, store.worker_leader_lease(), store.diagnostics())
+    );
+    host.report_startup_ready("Workers");
+    let served = host.serve(api.router()).await;
+    plugin_runtime.shutdown().await;
+    Ok(served?)
+}

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

@@ -0,0 +1,107 @@
+//! 启动模式共享的基础设施与 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::{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 version = host.system_update.version.clone();
+        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 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,
+    pub(super) peer: gateway_admin::PeerUpstreamBundle,
+}
+
+impl Providers {
+    pub(super) async fn initialize(
+        config: provider_openai::OpenAiConfig,
+        environment: &Environment,
+    ) -> Result<Self, BootstrapError> {
+        let ports = environment.store.provider_ports();
+        let upstream_reader = Arc::new(gateway_core::account::UpstreamInfoReader::default());
+        let openai = provider_openai::initialize(
+            config.with_timezone(environment.timezone),
+            ports.clone(),
+            upstream_reader.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 管理身份冲突"))?;
+        let peer = gateway_admin::initialize_peer_upstream(
+            environment.store.provider_ports().accounts(),
+            &admin,
+            Arc::new(gateway_host::peer::HttpPeerTransport::with_client_builder(
+                provider_openai::build_reqwest_client_with_custom_ca,
+            )),
+        )
+        .map_err(|_| gateway_admin::model::AdminError::invalid("互联后台任务配置无效"))?;
+        upstream_reader
+            .bind(&peer.scheduling_source())
+            .map_err(|_| gateway_admin::model::AdminError::invalid("互联观测端口重复绑定"))?;
+        Ok(Self {
+            peer,
+            openai,
+            xai,
+            core,
+            admin,
+        })
+    }
+}

backend/apps/gateway/src/lib.rs

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

backend/apps/gateway/src/main.rs

@@ -1,19 +1,85 @@
-use std::{env, error::Error, io};
+//! 网关命令行入口，选择启动模式并创建异步运行时
+
+use std::{
+    error::Error,
+    io::{self, Write},
+    process::ExitCode,
+};
 
 use provider_openai::ensure_rustls_provider;
 
-fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
+fn main() -> ExitCode {
+    match run() {
+        Ok(code) => code,
+        Err(error) => {
+            eprintln!("{error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run() -> Result<ExitCode, Box<dyn Error + Send + Sync>> {
     ensure_rustls_provider();
-    let mut arguments = env::args_os().skip(1);
-    match arguments.next().as_deref().and_then(|value| value.to_str()) {
+    let mut arguments = gateway_host::system_update::startup_arguments()?;
+    let command = arguments
+        .next()
+        .map(|value| {
+            value
+                .into_string()
+                .map_err(|_| invalid_cli("command must be UTF-8"))
+        })
+        .transpose()?;
+    match command.as_deref() {
         None | Some("serve") => {
             reject_extra_arguments(arguments)?;
             runtime()?.block_on(codex_proxy_rs::bootstrap::run())?;
-            Ok(())
+            Ok(ExitCode::SUCCESS)
         }
-        Some(command) => {
-            Err(invalid_cli(&format!("unknown command {command:?}; expected serve")).into())
+        Some("help" | "--help" | "-h") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "Usage: codex-proxy-rs [serve]\n       codex-proxy-rs plugin <instance-id> <command> [options]\n\n  --help     Show help without loading configuration\n  --version  Show version\n  plugin --help  List enabled plugin commands without starting HTTP"
+            );
+            Ok(ExitCode::SUCCESS)
         }
+        Some("--version" | "-V") => {
+            reject_extra_arguments(arguments)?;
+            println!(
+                "{}",
+                option_env!("CPR_VERSION").unwrap_or(env!("CARGO_PKG_VERSION"))
+            );
+            Ok(ExitCode::SUCCESS)
+        }
+        Some("plugin") => {
+            let arguments = arguments
+                .map(|value| {
+                    value
+                        .into_string()
+                        .map_err(|_| invalid_cli("plugin arguments must be UTF-8"))
+                })
+                .collect::<Result<Vec<_>, _>>()?;
+            let mut arguments = arguments.into_iter();
+            let instance_id = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            let name = arguments
+                .next()
+                .filter(|value| !matches!(value.as_str(), "--help" | "-h"));
+            if instance_id.is_none() && name.is_some() {
+                return Err(invalid_cli("unexpected plugin help arguments").into());
+            }
+            let output = runtime()?.block_on(codex_proxy_rs::bootstrap::plugin_command(
+                codex_proxy_rs::bootstrap::PluginCommand {
+                    instance_id,
+                    name,
+                    arguments: arguments.collect(),
+                },
+            ))?;
+            io::stdout().lock().write_all(output.stdout.as_bytes())?;
+            io::stderr().lock().write_all(output.stderr.as_bytes())?;
+            Ok(ExitCode::from(output.exit_code))
+        }
+        Some(_) => Err(invalid_cli("unknown command; expected serve, plugin, or --help").into()),
     }
 }
 
@@ -25,7 +91,7 @@ fn runtime() -> Result<tokio::runtime::Runtime, io::Error> {
 
 fn reject_extra_arguments(mut arguments: impl Iterator) -> Result<(), io::Error> {
     if arguments.next().is_some() {
-        return Err(invalid_cli("unexpected extra command arguments"));
+        return Err(invalid_cli("too many arguments"));
     }
     Ok(())
 }

backend/apps/gateway/tests/architecture.rs

@@ -1,20 +1,24 @@
-//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验。
+//! docs/architecture.md 依赖 DAG 与生产源码纪律的 workspace 级机器校验
 
 use std::{
     collections::{BTreeMap, BTreeSet},
     fs,
     path::{Path, PathBuf},
+    sync::OnceLock,
 };
 
 use syn::{Item, visit::Visit};
 
-/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则。
+/// workspace 成员冻结清单;新增 crate 必须同步扩展本文件的依赖规则
 pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
     "apps/gateway",
+    "apps/plugin-cli",
     "crates/gateway-admin",
     "crates/gateway-api",
     "crates/gateway-core",
     "crates/gateway-host",
+    "crates/gateway-plugin/runtime",
+    "crates/gateway-plugin/sdk",
     "crates/gateway-protocol",
     "crates/gateway-store",
     "crates/providers/openai",
@@ -23,22 +27,24 @@ pub(super) const WORKSPACE_MEMBERS: &[&str] = &[
 
 #[test]
 fn workspace_member_list_matches_the_frozen_dag_scope() {
-    let manifest =
-        fs::read_to_string(backend_root().join("Cargo.toml")).expect("read workspace manifest");
-    for member in WORKSPACE_MEMBERS {
-        assert!(
-            manifest.contains(&format!("\"{member}\"")),
-            "workspace must include {member}"
-        );
-    }
-    let member_count = manifest
-        .lines()
-        .map(str::trim)
-        .filter(|line| line.starts_with("\"apps/") || line.starts_with("\"crates/"))
-        .count();
+    let metadata = cargo_metadata_json();
+    let root = backend_root();
+    let actual: BTreeSet<_> = metadata["packages"]
+        .as_array()
+        .expect("Cargo packages")
+        .iter()
+        .map(|package| {
+            Path::new(package["manifest_path"].as_str().expect("package manifest"))
+                .parent()
+                .expect("package directory")
+                .strip_prefix(&root)
+                .expect("workspace member path")
+                .to_path_buf()
+        })
+        .collect();
     assert_eq!(
-        member_count,
-        WORKSPACE_MEMBERS.len(),
+        actual,
+        WORKSPACE_MEMBERS.iter().map(PathBuf::from).collect(),
         "new workspace members must extend the dependency DAG rules"
     );
 }
@@ -64,23 +70,38 @@ fn gateway_core_depends_on_no_http_db_redis_or_provider_crate() {
 #[test]
 fn core_value_owners_do_not_depend_on_execution_or_routing() {
     let root = backend_root().join("crates/gateway-core/src");
+    let reexports = read_root_reexport_owners(&root);
     for relative in super::rust_files(&root) {
         let allowed: Option<&[&str]> = match relative.to_str().expect("source path") {
             "validation.rs" => Some(&[]),
             "identity.rs" => Some(&["validation"]),
             "upstream.rs" => Some(&["validation"]),
             "event.rs" => Some(&["metering", "operation", "upstream", "validation"]),
+            "account/selection.rs" => Some(&["account", "concurrency", "identity", "validation"]),
+            "concurrency.rs" => Some(&["error"]),
             "account/store.rs" => Some(&["account", "error", "identity", "validation"]),
-            path if path.starts_with("policy/") => Some(&["account", "policy", "validation"]),
+            path if path.starts_with("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).with_root_reexports(&reexports);
         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}",
@@ -90,50 +111,301 @@ fn core_value_owners_do_not_depend_on_execution_or_routing() {
     }
 }
 
-#[derive(Default)]
-struct CrateReferences(BTreeSet<String>);
+#[test]
+fn domain_owner_paths_form_a_dag() {
+    for member in ["crates/gateway-core", "crates/gateway-admin"] {
+        assert_owner_paths_form_a_dag(member);
+    }
+}
 
-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());
+fn assert_owner_paths_form_a_dag(member: &str) {
+    let root = backend_root().join(member).join("src");
+    let reexports = read_root_reexport_owners(&root);
+    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).with_root_reexports(&reexports);
+        let owner = references.module_path[0].clone();
+        let source = fs::read_to_string(root.join(&relative)).expect("read owner source");
+        references.visit_file(&syn::parse_file(&source).expect("parse owner 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,
+                "{member} owner dependency cycle reaches {owner}"
+            );
+            if visited.insert(dependency.clone())
+                && let Some(next) = graph.get(&dependency)
+            {
+                pending.extend(next.iter().cloned());
+            }
+        }
+    }
+}
+
+#[test]
+fn shared_owners_do_not_depend_on_their_callers() {
+    let boundaries: &[(&str, &str, &[&str])] = &[
+        ("crates/providers/xai", "transport", &["credential"]),
+        ("crates/providers/openai", "transport", &["provider"]),
+        ("crates/gateway-api", "time", &["admin"]),
+        (
+            "crates/gateway-api",
+            "client_error",
+            &["admin", "openai", "middleware"],
+        ),
+        ("crates/gateway-api", "middleware", &["openai"]),
+        ("crates/gateway-host", "system_update", &["config"]),
+        ("crates/gateway-plugin/runtime", "package", &["callback"]),
+    ];
+    for &(member, owner, forbidden) in boundaries {
+        let root = backend_root().join(member).join("src");
+        let reexports = read_root_reexport_owners(&root);
+        for relative in super::rust_files(&root) {
+            let mut references =
+                CrateReferences::in_module(&relative).with_root_reexports(&reexports);
+            if references.module_path.first().map(String::as_str) != Some(owner) {
+                continue;
+            }
+            let source = fs::read_to_string(root.join(&relative)).expect("read owner source");
+            references.visit_file(&syn::parse_file(&source).expect("parse owner source"));
+            for dependency in forbidden {
+                assert!(
+                    !references.owners.contains(*dependency),
+                    "{member}/src/{} must not depend on crate::{dependency}",
+                    relative.display()
+                );
+            }
+        }
+    }
+}
+
+#[test]
+fn owner_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(),
+        ])
+    );
+}
+
+#[test]
+fn owner_reference_scan_resolves_crate_root_reexports() {
+    let root = syn::parse_file(
+        r#"
+        mod provider;
+        mod transport;
+        mod secret;
+        pub use provider::{OFFICIAL_URL, Options as ProviderOptions};
+        pub use self::transport::{self as network, Request};
+        pub use crate::secret::SecretValue;
+        pub use external::Unrelated;
+        "#,
+    )
+    .expect("parse root reexport fixture");
+    let syntax = syn::parse_file(
+        r#"
+        use crate::{OFFICIAL_URL, ProviderOptions, network::Client};
+        use super::super::SecretValue;
+        fn request() -> crate::Request { unimplemented!() }
+        "#,
+    )
+    .expect("parse reexport consumer fixture");
+    let reexports = root_reexport_owners(&root);
+    assert!(!reexports.contains_key("Unrelated"));
+    let mut references = CrateReferences::in_module(Path::new("consumer/request.rs"))
+        .with_root_reexports(&reexports);
+    references.visit_file(&syntax);
+    assert_eq!(
+        references.owners,
+        BTreeSet::from([
+            "provider".to_owned(),
+            "transport".to_owned(),
+            "secret".to_owned(),
+        ])
+    );
+}
+
+fn read_root_reexport_owners(root: &Path) -> BTreeMap<String, String> {
+    let source = fs::read_to_string(root.join("lib.rs")).expect("read crate root");
+    root_reexport_owners(&syn::parse_file(&source).expect("parse crate root"))
+}
+
+// 只解析根模块的显式重导出，不推断 glob、宏展开或完整 Rust 名称解析
+fn root_reexport_owners(syntax: &syn::File) -> BTreeMap<String, String> {
+    let modules = syntax
+        .items
+        .iter()
+        .filter_map(|item| match item {
+            Item::Mod(module) => Some(module.ident.to_string()),
+            _ => None,
+        })
+        .collect::<BTreeSet<_>>();
+    let mut reexports = BTreeMap::new();
+    for item in &syntax.items {
+        if let Item::Use(item) = item
+            && !matches!(item.vis, syn::Visibility::Inherited)
+        {
+            visit_use_leaves(&item.tree, &mut Vec::new(), &mut |path, name| {
+                let owner = path
+                    .iter()
+                    .find(|segment| !matches!(segment.as_str(), "crate" | "self"));
+                if let (Some(owner), Some(name)) = (owner, name)
+                    && modules.contains(owner)
+                {
+                    reexports.insert(name.to_owned(), owner.clone());
+                }
+            });
+        }
+    }
+    reexports
+}
+
+#[derive(Default)]
+struct CrateReferences<'a> {
+    owners: BTreeSet<String>,
+    module_path: Vec<String>,
+    root_reexports: Option<&'a BTreeMap<String, String>>,
+}
+
+impl<'ast> Visit<'ast> for CrateReferences<'_> {
+    fn visit_path(&mut self, path: &'ast syn::Path) {
+        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);
+        visit_use_leaves(&item.tree, &mut Vec::new(), &mut |path, _| {
+            self.record(path);
+        });
     }
 }
 
-impl CrateReferences {
-    fn use_tree(&mut self, tree: &syn::UseTree, crate_root: bool) {
-        match tree {
-            syn::UseTree::Path(path) if crate_root => {
-                self.0.insert(path.ident.to_string());
-            }
-            syn::UseTree::Name(name) if crate_root => {
-                self.0.insert(name.ident.to_string());
-            }
-            syn::UseTree::Rename(rename) if crate_root => {
-                self.0.insert(rename.ident.to_string());
-            }
-            syn::UseTree::Path(path) => self.use_tree(&path.tree, path.ident == "crate"),
-            syn::UseTree::Group(group) => {
-                for item in &group.items {
-                    self.use_tree(item, crate_root);
-                }
-            }
-            syn::UseTree::Glob(_) if crate_root => {
-                self.0.insert("*".to_owned());
-            }
-            _ => {}
+impl<'a> CrateReferences<'a> {
+    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,
+            root_reexports: None,
+        }
+    }
+
+    fn with_root_reexports(mut self, reexports: &'a BTreeMap<String, String>) -> Self {
+        self.root_reexports = Some(reexports);
+        self
+    }
+
+    fn root_owner(&self, name: &str) -> String {
+        self.root_reexports
+            .and_then(|reexports| reexports.get(name))
+            .cloned()
+            .unwrap_or_else(|| name.to_owned())
+    }
+
+    fn record(&mut self, path: &[String]) {
+        let Some(first) = path.first() else { return };
+        let owner = if first == "crate" {
+            path.get(1).map(|name| self.root_owner(name))
+        } 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()
+                .cloned()
+                .or_else(|| rest.first().map(|name| self.root_owner(name)))
+        } else {
+            None
+        };
+        if let Some(owner) = owner {
+            self.owners.insert(owner);
+        }
+    }
+}
+
+fn visit_use_leaves(
+    tree: &syn::UseTree,
+    prefix: &mut Vec<String>,
+    visit: &mut impl FnMut(&[String], Option<&str>),
+) {
+    match tree {
+        syn::UseTree::Path(path) => {
+            prefix.push(path.ident.to_string());
+            visit_use_leaves(&path.tree, prefix, visit);
+            prefix.pop();
+        }
+        syn::UseTree::Name(name) => {
+            let name = name.ident.to_string();
+            let export = if name == "self" {
+                prefix.last().cloned()
+            } else {
+                Some(name.clone())
+            };
+            prefix.push(name);
+            visit(prefix, export.as_deref());
+            prefix.pop();
+        }
+        syn::UseTree::Rename(rename) => {
+            prefix.push(rename.ident.to_string());
+            visit(prefix, Some(&rename.rename.to_string()));
+            prefix.pop();
+        }
+        syn::UseTree::Group(group) => {
+            for item in &group.items {
+                visit_use_leaves(item, prefix, visit);
+            }
+        }
+        syn::UseTree::Glob(_) => visit(prefix, None),
     }
 }
 
@@ -147,6 +419,13 @@ fn gateway_protocol_has_no_workspace_dependencies() {
     }
 }
 
+#[test]
+fn plugin_sdk_has_no_workspace_dependencies() {
+    for name in dependency_names("crates/gateway-plugin/sdk") {
+        assert!(!name.starts_with("gateway-") && !name.starts_with("provider-"));
+    }
+}
+
 #[test]
 fn provider_crates_do_not_depend_on_each_other() {
     assert_no_dependency("crates/providers/openai", &["provider-xai"]);
@@ -161,28 +440,40 @@ 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"),
     ("gateway-admin", "crates/gateway-admin"),
     ("gateway-api", "crates/gateway-api"),
     ("gateway-core", "crates/gateway-core"),
     ("gateway-host", "crates/gateway-host"),
+    ("gateway-plugin-runtime", "crates/gateway-plugin/runtime"),
+    ("gateway-plugin-sdk", "crates/gateway-plugin/sdk"),
     ("gateway-protocol", "crates/gateway-protocol"),
     ("gateway-store", "crates/gateway-store"),
     ("provider-openai", "crates/providers/openai"),
     ("provider-xai", "crates/providers/xai"),
 ];
 
-/// Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计。
+/// SDK 与 Adapter/provider 根门面的稳定合同模块；任何增减都必须同步完成边界审计
 const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
-    ("crates/gateway-api", &["admin", "openai"]),
+    ("crates/gateway-plugin/sdk", &["call", "client"]),
+    ("crates/gateway-plugin/runtime", &[]),
+    ("crates/gateway-api", &["admin", "auth", "openai"]),
     (
         "crates/gateway-host",
         &[
             "client_distribution",
             "config",
+            "outbound",
+            "peer",
+            "official_plugins",
+            "pricing",
+            "plugin_distribution",
+            "process",
             "proxy_probe",
+            "retention",
             "serve",
             "system_update",
             "workers",
@@ -193,33 +484,39 @@ const ADAPTER_PUBLIC_MODULES: &[(&str, &[&str])] = &[
         "crates/providers/openai",
         &["config", "credential", "transport"],
     ),
-    (
-        "crates/providers/xai",
-        &["config", "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"),
     ("codex-proxy-rs", "gateway-api"),
     ("codex-proxy-rs", "gateway-core"),
     ("codex-proxy-rs", "gateway-host"),
+    ("codex-proxy-rs", "gateway-plugin-runtime"),
     ("codex-proxy-rs", "gateway-store"),
     ("codex-proxy-rs", "provider-openai"),
     ("codex-proxy-rs", "provider-xai"),
     ("gateway-admin", "gateway-core"),
+    ("gateway-admin", "gateway-protocol"),
     ("gateway-api", "gateway-admin"),
     ("gateway-api", "gateway-core"),
     ("gateway-api", "gateway-protocol"),
     ("gateway-host", "gateway-admin"),
     ("gateway-host", "gateway-core"),
+    ("gateway-host", "gateway-protocol"),
+    ("gateway-plugin-runtime", "gateway-host"),
+    ("gateway-plugin-runtime", "gateway-core"),
+    ("gateway-plugin-runtime", "gateway-admin"),
+    ("gateway-plugin-runtime", "gateway-plugin-sdk"),
+    ("gateway-plugin-runtime", "gateway-protocol"),
     ("gateway-store", "gateway-admin"),
     ("gateway-store", "gateway-core"),
     ("provider-openai", "gateway-admin"),
@@ -233,7 +530,7 @@ const ALLOWED_INTERNAL_EDGES: &[(&str, &str)] = &[
 #[test]
 fn workspace_internal_dependency_edges_match_frozen_dag() {
     let metadata = cargo_metadata_json();
-    let actual = workspace_runtime_dependency_edges(&metadata);
+    let actual = workspace_runtime_dependency_edges(metadata);
     let mut expected: Vec<(String, String)> = ALLOWED_INTERNAL_EDGES
         .iter()
         .map(|(from, to)| ((*from).to_owned(), (*to).to_owned()))
@@ -330,33 +627,45 @@ fn adapter_public_module_surfaces_match_allowlist() {
 }
 
 #[test]
-fn production_sources_do_not_host_tests() {
+fn workspace_modules_follow_conventional_file_layout() {
+    let targets = test_source_roots();
     for member in WORKSPACE_MEMBERS {
-        let src = backend_root().join(member).join("src");
-        let sources = super::rust_files(&src);
-        assert!(!sources.is_empty(), "{member} has no production sources");
-        for relative in sources {
-            let path = src.join(relative);
-            let source = fs::read_to_string(&path).expect("read production source");
-            assert!(
-                !source.contains("#[cfg(test)]"),
-                "{} hosts tests in production src",
-                path.display()
+        let member_root = backend_root().join(member);
+        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() {
+            let roots = targets.get(&tests).expect("Cargo test source roots");
+            assert_module_tree(
+                &tests,
+                &roots.iter().map(String::as_str).collect::<Vec<_>>(),
             );
         }
     }
 }
 
-#[test]
-fn workspace_modules_follow_conventional_file_layout() {
-    for member in WORKSPACE_MEMBERS {
-        let member_root = backend_root().join(member);
-        assert_module_tree(&member_root.join("src"), &["lib.rs", "main.rs"]);
-
-        let tests = member_root.join("tests");
-        if tests.is_dir() {
-            assert_module_tree(&tests, &["main.rs"]);
+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(),
+        );
     }
 }
 
@@ -368,6 +677,7 @@ enum ModuleLayout {
 
 #[test]
 fn integration_tests_mirror_production_module_tree() {
+    let targets = test_source_roots();
     for member in WORKSPACE_MEMBERS {
         let member_root = backend_root().join(member);
         let tests_root = member_root.join("tests");
@@ -376,9 +686,13 @@ fn integration_tests_mirror_production_module_tree() {
         }
 
         let production = module_layouts(&member_root.join("src"), &["lib.rs", "main.rs"]);
-        let tests = module_layouts(&tests_root, &["main.rs"]);
+        let roots = targets.get(&tests_root).expect("Cargo test source roots");
+        let tests = module_layouts(
+            &tests_root,
+            &roots.iter().map(String::as_str).collect::<Vec<_>>(),
+        );
         for (module, test_layout) in tests {
-            if module == Path::new("support") {
+            if module.starts_with("support") {
                 continue;
             }
 
@@ -408,6 +722,28 @@ fn integration_tests_mirror_production_module_tree() {
     }
 }
 
+/// Rust 子进程 fixture 是 Cargo 的独立 crate 根，不能要求它由测试模块再次声明
+fn test_source_roots() -> BTreeMap<PathBuf, Vec<String>> {
+    let metadata = cargo_metadata_json();
+    let mut roots = BTreeMap::<PathBuf, Vec<String>>::new();
+    for package in metadata["packages"].as_array().expect("Cargo packages") {
+        let root = Path::new(package["manifest_path"].as_str().expect("package manifest"))
+            .parent()
+            .expect("package directory")
+            .join("tests");
+        for target in package["targets"].as_array().expect("Cargo targets") {
+            let source = Path::new(target["src_path"].as_str().expect("target source"));
+            if let Ok(relative) = source.strip_prefix(&root) {
+                roots
+                    .entry(root.clone())
+                    .or_default()
+                    .push(relative.to_str().expect("UTF-8 source path").to_owned());
+            }
+        }
+    }
+    roots
+}
+
 fn module_layouts(root: &Path, crate_roots: &[&str]) -> BTreeMap<PathBuf, ModuleLayout> {
     super::rust_files(root)
         .into_iter()
@@ -440,6 +776,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()
@@ -502,7 +840,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,
@@ -513,23 +858,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 {
@@ -539,40 +882,46 @@ pub(super) fn backend_root() -> PathBuf {
         .expect("backend workspace root")
 }
 
-fn cargo_metadata_json() -> serde_json::Value {
-    let output = std::process::Command::new("cargo")
-        .args(["metadata", "--format-version", "1", "--no-deps"])
-        .current_dir(backend_root())
-        .output()
-        .expect("run cargo metadata");
-    assert!(
-        output.status.success(),
-        "cargo metadata failed: {}",
-        String::from_utf8_lossy(&output.stderr)
-    );
-    serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
+fn cargo_metadata_json() -> &'static serde_json::Value {
+    static METADATA: OnceLock<serde_json::Value> = OnceLock::new();
+    METADATA.get_or_init(|| {
+        let output = std::process::Command::new("cargo")
+            .args(["metadata", "--format-version", "1", "--no-deps", "--locked"])
+            .current_dir(backend_root())
+            .output()
+            .expect("run cargo metadata");
+        assert!(
+            output.status.success(),
+            "cargo metadata failed: {}",
+            String::from_utf8_lossy(&output.stderr)
+        );
+        serde_json::from_slice(&output.stdout).expect("parse cargo metadata")
+    })
 }
 
-/// 提取成员 `[dependencies]` 段内声明的依赖名;段落以下一个 `[` 表头结束。
+/// 复用 Cargo 解析后的实际包名，覆盖重命名依赖与平台条件，排除测试和构建依赖
 fn dependency_names(member: &str) -> Vec<String> {
-    let manifest = fs::read_to_string(backend_root().join(member).join("Cargo.toml"))
-        .expect("read member manifest");
-    let mut in_dependencies = false;
-    let mut names = Vec::new();
-    for line in manifest.lines() {
-        let line = line.trim();
-        if line.starts_with('[') {
-            in_dependencies = line == "[dependencies]";
-            continue;
-        }
-        if !in_dependencies || line.is_empty() || line.starts_with('#') {
-            continue;
-        }
-        if let Some((name, _)) = line.split_once('=') {
-            names.push(name.trim().to_owned());
-        }
-    }
-    names
+    let manifest = backend_root().join(member).join("Cargo.toml");
+    let package = cargo_metadata_json()["packages"]
+        .as_array()
+        .expect("Cargo packages")
+        .iter()
+        .find(|package| {
+            Path::new(package["manifest_path"].as_str().expect("package manifest")) == manifest
+        })
+        .expect("workspace member");
+    package["dependencies"]
+        .as_array()
+        .expect("package dependencies")
+        .iter()
+        .filter(|dependency| dependency["kind"].is_null())
+        .map(|dependency| {
+            dependency["name"]
+                .as_str()
+                .expect("dependency name")
+                .to_owned()
+        })
+        .collect()
 }
 
 fn assert_no_dependency(member: &str, forbidden: &[&str]) {

backend/apps/gateway/tests/bootstrap.rs

@@ -1,383 +0,0 @@
-use std::{fs, process::Command};
-
-use codex_proxy_rs::bootstrap::GatewayConfig;
-use gateway_host::LoadableConfig;
-
-const CONFIG_EXAMPLE: &str = include_str!("../../../../deploy/config.example.yaml");
-const POSTGRES_PASSWORD: &str = "111111111111111111111111111111111111111111111111";
-const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
-const ADMIN_PASSWORD: &str = "test-admin-password";
-const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
-
-#[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).await;
-    assert!(result.success, "{}", result.message);
-    assert_eq!(result.exit_ip.unwrap().to_string(), "203.0.113.8");
-    tokio::time::timeout(Duration::from_secs(5), server)
-        .await
-        .unwrap()
-        .unwrap();
-}
-
-fn generate_proxy_test_certificates(directory: &std::path::Path) {
-    let openssl = |args: &[&str]| {
-        let output = Command::new("openssl")
-            .args(args)
-            .current_dir(directory)
-            .output()
-            .unwrap();
-        assert!(
-            output.status.success(),
-            "{}",
-            String::from_utf8_lossy(&output.stderr)
-        );
-    };
-    openssl(&[
-        "req",
-        "-x509",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "ca.key",
-        "-out",
-        "ca.pem",
-        "-days",
-        "1",
-        "-subj",
-        "/CN=Proxy Test CA",
-    ]);
-    openssl(&[
-        "req",
-        "-newkey",
-        "rsa:2048",
-        "-nodes",
-        "-keyout",
-        "server.key",
-        "-out",
-        "server.csr",
-        "-subj",
-        "/CN=localhost",
-    ]);
-    fs::write(directory.join("extensions"), "subjectAltName=IP:127.0.0.1\nbasicConstraints=critical,CA:FALSE\nkeyUsage=digitalSignature,keyEncipherment\nextendedKeyUsage=serverAuth\n").unwrap();
-    openssl(&[
-        "x509",
-        "-req",
-        "-in",
-        "server.csr",
-        "-CA",
-        "ca.pem",
-        "-CAkey",
-        "ca.key",
-        "-CAcreateserial",
-        "-out",
-        "server.pem",
-        "-days",
-        "1",
-        "-extfile",
-        "extensions",
-    ]);
-}
-
-#[test]
-fn config_loader_should_load_complete_terminal_example() {
-    parse_config(&valid_config()).expect("terminal config example");
-}
-
-#[test]
-fn config_loader_should_resolve_paths_relative_to_config_file() {
-    let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
-    let debug = format!("{config:?}");
-    assert!(debug.contains(".runtime/data"));
-    assert!(debug.contains(".runtime/logs"));
-    assert!(debug.contains("frontend/dist"));
-}
-
-#[test]
-fn config_loader_should_reject_missing_runtime_data_dir() {
-    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
-
-    assert!(parse_config(&config).is_err());
-}
-
-#[test]
-fn config_loader_should_inject_connection_passwords_into_urls() {
-    parse_config(&valid_config()).expect("Store validates password injection into both URLs");
-}
-
-#[test]
-fn config_loader_should_apply_only_explicit_topology_overrides() {
-    let invalid = valid_config()
-        .replace("host: '127.0.0.1'", "host: ''")
-        .replace("port: 8080", "port: 0")
-        .replace(
-            "url: 'postgres://codex_proxy@127.0.0.1:5432/codex_proxy'",
-            "url: 'invalid-postgres-url'",
-        )
-        .replace("url: 'redis://127.0.0.1:6379/'", "url: 'invalid-redis-url'")
-        .replace(POSTGRES_PASSWORD, "invalid-postgres-password")
-        .replace(REDIS_PASSWORD, "invalid-redis-password");
-    if std::env::var_os(TOPOLOGY_CHILD_ENV).is_some() {
-        parse_config(&invalid).expect("explicit package-owned environment overrides");
-        return;
-    }
-    assert!(parse_config(&invalid).is_err());
-    let status = Command::new(std::env::current_exe().expect("current test executable"))
-        .args([
-            "--exact",
-            "bootstrap::config_loader_should_apply_only_explicit_topology_overrides",
-        ])
-        .env(TOPOLOGY_CHILD_ENV, "1")
-        .env("CPR_SERVER_HOST", "127.0.0.1")
-        .env("CPR_SERVER_PORT", "8080")
-        .env(
-            "CPR_DATABASE_URL",
-            "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
-        )
-        .env("CPR_REDIS_URL", "redis://127.0.0.1:6379/")
-        .env("CPR_DATABASE_PASSWORD", POSTGRES_PASSWORD)
-        .env("CPR_REDIS_PASSWORD", REDIS_PASSWORD)
-        .status()
-        .expect("run isolated environment override test");
-    assert!(status.success());
-}
-
-#[test]
-fn bootstrap_config_debug_should_redact_all_passwords() {
-    let (config, _directory) = parse_config(&valid_config()).expect("config");
-    let debug = format!("{config:?}");
-    assert!(!debug.contains(POSTGRES_PASSWORD));
-    assert!(!debug.contains(REDIS_PASSWORD));
-    assert!(!debug.contains(ADMIN_PASSWORD));
-    assert!(debug.contains("[REDACTED]"));
-}
-
-#[test]
-fn config_loader_should_reject_unknown_fields() {
-    assert_rejected(format!(
-        "{}\nunknown_terminal_field: true\n",
-        valid_config()
-    ));
-}
-
-#[test]
-fn config_loader_should_reject_removed_tls_section() {
-    assert_rejected(valid_config().replace("openai:\n", "openai:\n  tls: {}\n"));
-}
-
-#[test]
-fn config_loader_should_reject_missing_explicit_fields() {
-    assert_rejected(valid_config().replace("  request_id_header: 'x-request-id'\n", ""));
-}
-
-#[test]
-fn config_loader_should_reject_unsupported_schema_version() {
-    assert_rejected(valid_config().replace("schema_version: 1", "schema_version: 2"));
-}
-
-#[test]
-fn config_loader_should_reject_embedded_database_password() {
-    assert_rejected(valid_config().replace(
-        "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
-        "postgres://codex_proxy:embedded@127.0.0.1:5432/codex_proxy",
-    ));
-}
-
-#[test]
-fn config_loader_should_reject_non_hex_postgres_password() {
-    assert_rejected(valid_config().replace(POSTGRES_PASSWORD, &"g".repeat(48)));
-}
-
-#[test]
-fn config_loader_should_reject_wrong_length_redis_password() {
-    assert_rejected(valid_config().replace(REDIS_PASSWORD, "1234"));
-}
-
-#[test]
-fn config_loader_should_reject_weak_admin_password() {
-    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "password"));
-}
-
-#[test]
-fn config_loader_should_reject_admin_password_with_compose_interpolation() {
-    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "unsafe$password"));
-}
-
-#[test]
-fn config_loader_should_reject_removed_fingerprint_section() {
-    assert_rejected(valid_config().replace(
-        "openai:\n",
-        "openai:\n  fingerprint:\n    browser: removed\n",
-    ));
-}
-
-#[test]
-fn config_loader_should_reject_invalid_codex_cli_version() {
-    assert_rejected(valid_config().replace("codex_version: '0.153.4'", "codex_version: 'latest'"));
-}
-
-#[test]
-fn config_loader_should_reject_disabled_all_log_outputs() {
-    assert_rejected(
-        valid_config()
-            .replace("stdout: true", "stdout: false")
-            .replace("enabled: true", "enabled: false"),
-    );
-}
-
-#[test]
-fn config_loader_should_reject_zero_server_port() {
-    assert_rejected(valid_config().replace("port: 8080", "port: 0"));
-}
-
-#[test]
-fn config_loader_should_reject_invalid_desktop_profile_fields() {
-    assert_rejected(valid_config().replace("desktop_build: '8109'", "desktop_build: 'build'"));
-}
-
-#[test]
-fn config_loader_should_accept_empty_and_custom_request_locations() {
-    let original = valid_config();
-    let omitted = original
-        .lines()
-        .filter(|line| !line.trim_start().starts_with("location:"))
-        .collect::<Vec<_>>()
-        .join("\n");
-    assert_ne!(original, omitted);
-    parse_config(&omitted).expect("location passthrough when omitted");
-    let location_line = original
-        .lines()
-        .find(|line| line.trim_start().starts_with("location:"))
-        .expect("example location");
-    for empty in ["    location:", "    location: null", "    location: ~"] {
-        parse_config(&original.replace(location_line, empty)).expect("empty YAML location");
-    }
-    let custom = original.replace(
-        "location: { country: 'US', region: 'Ohio', city: 'Piketon', timezone: 'America/New_York' }",
-        "location: { country: 'NZ', region: 'Auckland', city: 'Auckland', timezone: 'Pacific/Auckland' }",
-    );
-    assert_ne!(original, custom);
-    parse_config(&custom).expect("custom location from YAML");
-}
-
-#[test]
-fn config_loader_should_reject_invalid_request_location_timezones() {
-    let original = valid_config();
-    let invalid = original.replace("timezone: 'America/New_York'", "timezone: 'Not/A_Timezone'");
-    assert_ne!(original, invalid);
-    assert_rejected(invalid);
-}
-
-fn assert_rejected(config: String) {
-    assert!(parse_config(&config).is_err());
-}
-
-fn valid_config() -> String {
-    CONFIG_EXAMPLE
-        .replacen(
-            "password: &postgres_password ''",
-            &format!("password: &postgres_password '{POSTGRES_PASSWORD}'"),
-            1,
-        )
-        .replacen(
-            "password: &redis_password ''",
-            &format!("password: &redis_password '{REDIS_PASSWORD}'"),
-            1,
-        )
-        .replace(
-            "default_password: ''",
-            &format!("default_password: '{ADMIN_PASSWORD}'"),
-        )
-}
-
-fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), String> {
-    let directory = tempfile::tempdir().map_err(|error| error.to_string())?;
-    let deploy = directory.path().join("deploy");
-    fs::create_dir(&deploy).map_err(|error| error.to_string())?;
-    let path = deploy.join("config.yaml");
-    fs::write(&path, config).map_err(|error| error.to_string())?;
-    let mut config = config::Config::builder()
-        .add_source(config::File::from(path).required(true))
-        .build()
-        .and_then(config::Config::try_deserialize::<GatewayConfig>)
-        .map_err(|error| error.to_string())?;
-    config
-        .resolve_and_validate(&deploy)
-        .map_err(|error| error.to_string())?;
-    Ok((config, directory))
-}

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

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

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

@@ -0,0 +1,461 @@
+//! 验证顶层配置加载、路径解析、显式覆盖与敏感字段脱敏
+
+use std::{fs, process::Command};
+
+use codex_proxy_rs::bootstrap::GatewayConfig;
+use gateway_host::LoadableConfig;
+
+const CONFIG_EXAMPLE: &str = include_str!("../../../../../deploy/config.example.yaml");
+const POSTGRES_PASSWORD: &str = "111111111111111111111111111111111111111111111111";
+const REDIS_PASSWORD: &str = "222222222222222222222222222222222222222222222222";
+const ADMIN_PASSWORD: &str = "test-admin-password";
+const TOPOLOGY_CHILD_ENV: &str = "CPR_TEST_TOPOLOGY_CHILD";
+
+#[test]
+fn config_loader_should_load_complete_terminal_example() {
+    parse_config(&valid_config()).expect("terminal config example");
+}
+
+#[test]
+fn config_loader_should_resolve_paths_relative_to_config_file() {
+    let (config, _directory) = parse_config(&valid_config()).expect("resolved config");
+    let debug = format!("{config:?}");
+    assert!(debug.contains(".runtime/data"));
+    assert!(debug.contains(".runtime/logs"));
+    assert!(debug.contains("frontend/dist"));
+}
+
+#[test]
+fn config_loader_should_share_resolved_assets_with_system_update() {
+    const CHILD_ENV: &str = "CPR_TEST_UPDATE_ASSETS_CHILD";
+    let Ok(case) = std::env::var(CHILD_ENV) else {
+        // 使用子进程覆盖无环境变量、Docker 路径和相对路径，避免污染并行测试
+        for (case, web_dist) in [
+            ("binary", None),
+            ("docker", Some("/app/web/dist")),
+            ("relative", Some("../custom/dist")),
+        ] {
+            let mut child = Command::new(std::env::current_exe().expect("test executable"));
+            child
+                .args([
+                    "--exact",
+                    "bootstrap::config::config_loader_should_share_resolved_assets_with_system_update",
+                ])
+                .env(CHILD_ENV, case)
+                .env_remove("CPR_WEB_DIST_DIR");
+            if let Some(web_dist) = web_dist {
+                child.env("CPR_WEB_DIST_DIR", web_dist);
+            }
+            let output = child.output().expect("isolated configuration test");
+            assert!(
+                output.status.success(),
+                "{case}: {}\n{}",
+                String::from_utf8_lossy(&output.stdout),
+                String::from_utf8_lossy(&output.stderr)
+            );
+        }
+        return;
+    };
+    let mut document = valid_config_document();
+    document["api"]["asset_directory"] = serde_json::json!("../web/dist");
+    let (config, directory) = parse_config(&document.to_string()).expect("binary configuration");
+    let assets = match case.as_str() {
+        "docker" => std::path::PathBuf::from("/app/web/dist"),
+        "relative" => directory.path().join("deploy/../custom/dist"),
+        _ => directory.path().join("deploy/../web/dist"),
+    };
+    let debug = format!("{config:?}");
+    assert!(debug.contains(&format!("asset_directory: {assets:?}")));
+    assert!(debug.contains(&format!("web_dist_dir: Some({assets:?})")));
+}
+
+#[test]
+fn config_loader_should_reject_missing_runtime_data_dir() {
+    let config = valid_config().replace("  runtime_data_dir: '../.runtime/data'\n", "");
+
+    assert!(parse_config(&config).is_err());
+}
+
+#[test]
+fn config_loader_should_apply_only_explicit_topology_overrides() {
+    let invalid = valid_config()
+        .replace("host: '127.0.0.1'", "host: ''")
+        .replace("port: 8080", "port: 0")
+        .replace(
+            "url: 'postgres://codex_proxy@127.0.0.1:5432/codex_proxy'",
+            "url: 'invalid-postgres-url'",
+        )
+        .replace("url: 'redis://127.0.0.1:6379/'", "url: 'invalid-redis-url'")
+        .replace(POSTGRES_PASSWORD, "invalid-postgres-password")
+        .replace(REDIS_PASSWORD, "invalid-redis-password");
+    if std::env::var_os(TOPOLOGY_CHILD_ENV).is_some() {
+        parse_config(&invalid).expect("explicit package-owned environment overrides");
+        return;
+    }
+    assert!(parse_config(&invalid).is_err());
+    let status = Command::new(std::env::current_exe().expect("current test executable"))
+        .args([
+            "--exact",
+            "bootstrap::config::config_loader_should_apply_only_explicit_topology_overrides",
+        ])
+        .env(TOPOLOGY_CHILD_ENV, "1")
+        .env("CPR_SERVER_HOST", "127.0.0.1")
+        .env("CPR_SERVER_PORT", "8080")
+        .env(
+            "CPR_DATABASE_URL",
+            "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
+        )
+        .env("CPR_REDIS_URL", "redis://127.0.0.1:6379/")
+        .env(
+            "CPR_DATABASE_PASSWORD",
+            "RdsTest9!abcdefGhRdsTest9!abcdefGh",
+        )
+        .env("CPR_REDIS_PASSWORD", "ManagedRedis9!abcdefGh")
+        .status()
+        .expect("run isolated environment override test");
+    assert!(status.success());
+}
+
+#[test]
+fn bootstrap_config_debug_should_redact_all_passwords() {
+    let (config, _directory) = parse_config(&valid_config()).expect("config");
+    let debug = format!("{config:?}");
+    assert!(!debug.contains(POSTGRES_PASSWORD));
+    assert!(!debug.contains(REDIS_PASSWORD));
+    assert!(!debug.contains(ADMIN_PASSWORD));
+    assert!(debug.contains("[REDACTED]"));
+}
+
+#[test]
+fn config_loader_should_ignore_unknown_fields_in_configuration_sections() {
+    let mut document = valid_config_document();
+    document["host"]["system_update"] = serde_json::json!({});
+    document["store"]["pool"] = serde_json::json!({});
+    for path in [
+        "",
+        "/host",
+        "/host/listen",
+        "/host/logging",
+        "/host/logging/file",
+        "/host/system_update",
+        "/store",
+        "/store/database",
+        "/store/redis",
+        "/store/pool",
+        "/admin",
+        "/client",
+        "/api",
+        "/openai",
+    ] {
+        let mut extended = document.clone();
+        extended.pointer_mut(path).expect("configuration section")["unused_setting"] =
+            serde_json::json!({"nested": [true, null, "ignored"]});
+        parse_config(&extended.to_string())
+            .unwrap_or_else(|error| panic!("unknown field in {path}: {error}"));
+    }
+}
+
+#[test]
+fn config_loader_should_reject_invalid_known_fields_alongside_unknown_fields() {
+    for port in [serde_json::json!(0), serde_json::json!("not-a-port")] {
+        let mut document = valid_config_document();
+        document["host"]["listen"]["unused_setting"] = serde_json::json!(true);
+        document["host"]["listen"]["port"] = port;
+        assert_rejected(document.to_string());
+    }
+}
+
+#[test]
+fn config_loader_should_report_startup_configuration_diagnostics() {
+    const CHILD_ENV: &str = "CPR_TEST_CONFIG_DIAGNOSTICS_CHILD";
+    const UNUSED_SECRET: &str = "unused-value-must-not-appear-in-diagnostics";
+    if std::env::var_os(CHILD_ENV).is_some() {
+        gateway_host::load_config::<GatewayConfig>().expect("startup configuration");
+        return;
+    }
+    for case in [
+        "normal",
+        "unused",
+        "missing",
+        "timezoneEmpty",
+        "timezoneInvalid",
+        "timezoneNull",
+        "timezoneType",
+    ] {
+        let mut document = valid_config_document();
+        if case == "unused" {
+            document["openai"]["unused_setting"] = serde_json::json!(UNUSED_SECRET);
+        } else if case == "missing" {
+            document["host"]["listen"]
+                .as_object_mut()
+                .unwrap()
+                .remove("port");
+        }
+        if case.starts_with("timezone") {
+            document["host"]["timezone"] = match case {
+                "timezoneEmpty" => serde_json::json!(""),
+                "timezoneInvalid" => serde_json::json!(UNUSED_SECRET),
+                "timezoneNull" => serde_json::json!(null),
+                _ => serde_json::json!(8),
+            };
+        }
+        let directory = tempfile::tempdir().unwrap();
+        fs::create_dir(directory.path().join("deploy")).unwrap();
+        fs::write(
+            directory.path().join("deploy/config.yaml"),
+            document.to_string(),
+        )
+        .unwrap();
+        let output = Command::new(std::env::current_exe().unwrap())
+            .args([
+                "--exact",
+                "bootstrap::config::config_loader_should_report_startup_configuration_diagnostics",
+                "--nocapture",
+            ])
+            .env(CHILD_ENV, "1")
+            .current_dir(directory.path())
+            .output()
+            .unwrap();
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        assert_eq!(
+            output.status.success(),
+            case != "missing" && !case.starts_with("timezone"),
+            "{case}: {stderr}"
+        );
+        match case {
+            "unused" => assert!(
+                stderr.contains("openai.unused_setting") && stderr.contains("已忽略"),
+                "{stderr}"
+            ),
+            "missing" => assert!(stderr.contains("host.listen.port"), "{stderr}"),
+            case if case.starts_with("timezone") => {
+                assert!(stderr.contains("host.timezone"), "{stderr}")
+            }
+            _ => assert!(!stderr.contains("警告"), "{stderr}"),
+        }
+        assert!(!stderr.contains(UNUSED_SECRET), "{stderr}");
+        assert!(!stderr.contains("services"), "{stderr}");
+    }
+}
+
+#[test]
+fn config_loader_should_reject_missing_explicit_fields() {
+    assert_rejected(valid_config().replace("  request_id_header: 'x-request-id'\n", ""));
+}
+
+#[test]
+fn config_loader_should_allow_missing_provider_configuration() {
+    let mut document = valid_config_document();
+    document.as_object_mut().unwrap().remove("openai");
+    document.as_object_mut().unwrap().remove("xai");
+    parse_config(&document.to_string()).expect("providers use defaults when omitted");
+}
+
+#[test]
+fn config_loader_should_reject_unsupported_schema_version() {
+    assert_rejected(valid_config().replace("schema_version: 1", "schema_version: 2"));
+}
+
+#[test]
+fn config_loader_should_reject_embedded_database_password() {
+    assert_rejected(valid_config().replace(
+        "postgres://codex_proxy@127.0.0.1:5432/codex_proxy",
+        "postgres://codex_proxy:embedded@127.0.0.1:5432/codex_proxy",
+    ));
+}
+
+#[test]
+fn config_loader_should_accept_managed_store_passwords() {
+    for password in [
+        "RdsTest9!abcdefGh".to_owned(),
+        "RdsTest9!abcdefGhRdsTest9!abcdefGh".to_owned(),
+        POSTGRES_PASSWORD.to_owned(),
+        "x".repeat(128),
+        "Managed@:/?#%&+Password9!".to_owned(),
+        "数据库密码".repeat(4),
+    ] {
+        for field in ["database", "redis"] {
+            let mut document = valid_config_document();
+            document["store"][field]["password"] = serde_json::json!(password);
+            let (config, _directory) =
+                parse_config(&document.to_string()).expect("managed store password");
+            assert!(!format!("{config:?}").contains(&password));
+        }
+    }
+}
+
+#[test]
+fn config_loader_should_reject_invalid_store_passwords() {
+    for password in [
+        String::new(),
+        "x".repeat(15),
+        "x".repeat(129),
+        " ".repeat(32),
+        "\u{3000}".repeat(6),
+        "数据库密码".repeat(9),
+        "RdsTest9!abcdefGh\u{0000}".to_owned(),
+        "RdsTest9!abcdefGh\n".to_owned(),
+        "RdsTest9!abcdefGh\t".to_owned(),
+        "RdsTest9!abcdefGh\u{007f}".to_owned(),
+    ] {
+        for field in ["database", "redis"] {
+            let mut document = valid_config_document();
+            document["store"][field]["password"] = serde_json::json!(password);
+            assert_rejected(document.to_string());
+        }
+    }
+}
+
+#[test]
+fn config_loader_should_reject_embedded_redis_password() {
+    assert_rejected(valid_config().replace(
+        "redis://127.0.0.1:6379/",
+        "redis://default:embedded@127.0.0.1:6379/",
+    ));
+}
+
+#[test]
+fn config_loader_should_reject_weak_admin_password() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "password"));
+}
+
+#[test]
+fn config_loader_should_reject_admin_password_with_compose_interpolation() {
+    assert_rejected(valid_config().replace(ADMIN_PASSWORD, "unsafe$password"));
+}
+
+#[test]
+fn config_loader_should_reject_zero_client_session_ttl() {
+    let mut config = valid_config_document();
+    *config
+        .pointer_mut("/client/session_ttl_minutes")
+        .expect("example client session TTL") = serde_json::json!(0);
+    assert_rejected(config.to_string());
+}
+
+#[test]
+fn config_loader_should_default_missing_client_section() {
+    let mut config = valid_config_document();
+    config
+        .as_object_mut()
+        .expect("example config mapping")
+        .remove("client")
+        .expect("example client section");
+    parse_config(&config.to_string()).expect("client defaults when the section is omitted");
+}
+
+#[test]
+fn config_loader_should_reject_missing_client_session_ttl() {
+    let mut config = valid_config_document();
+    config["client"]
+        .as_object_mut()
+        .expect("example client mapping")
+        .remove("session_ttl_minutes")
+        .expect("example client session TTL");
+    assert_rejected(config.to_string());
+}
+
+#[test]
+fn config_loader_should_reject_disabled_all_log_outputs() {
+    assert_rejected(
+        valid_config()
+            .replace("stdout: true", "stdout: false")
+            .replace("enabled: true", "enabled: false"),
+    );
+}
+
+#[test]
+fn config_loader_should_reject_zero_server_port() {
+    assert_rejected(valid_config().replace("port: 8080", "port: 0"));
+}
+
+#[test]
+fn config_loader_should_accept_optional_openai_routing_strings() {
+    for value in [
+        serde_json::Value::Null,
+        serde_json::json!("us"),
+        serde_json::json!("custom-value"),
+        serde_json::json!(""),
+    ] {
+        let mut document = valid_config_document();
+        document["openai"]["residency"] = value.clone();
+        document["openai"]["account_routing_override"] = value;
+        parse_config(&document.to_string()).expect("optional routing strings");
+    }
+    let mut document = valid_config_document();
+    document["openai"]
+        .as_object_mut()
+        .unwrap()
+        .remove("residency");
+    document["openai"]
+        .as_object_mut()
+        .unwrap()
+        .remove("account_routing_override");
+    parse_config(&document.to_string()).expect("omitted routing strings");
+}
+
+fn assert_rejected(config: String) {
+    assert!(parse_config(&config).is_err());
+}
+
+fn valid_config() -> String {
+    CONFIG_EXAMPLE
+        .replacen(
+            "password: &postgres_password ''",
+            &format!("password: &postgres_password '{POSTGRES_PASSWORD}'"),
+            1,
+        )
+        .replacen(
+            "password: &redis_password ''",
+            &format!("password: &redis_password '{REDIS_PASSWORD}'"),
+            1,
+        )
+        .replace(
+            "default_password: ''",
+            &format!("default_password: '{ADMIN_PASSWORD}'"),
+        )
+}
+
+fn valid_config_document() -> serde_json::Value {
+    // 按字段修改样例，避免注释或排版变化让测试输入悄悄失效；JSON 仍可由 YAML 文件入口加载
+    config::Config::builder()
+        .add_source(config::File::from_str(
+            &valid_config(),
+            config::FileFormat::Yaml,
+        ))
+        .build()
+        .and_then(config::Config::try_deserialize)
+        .expect("example config document")
+}
+
+fn parse_config(config: &str) -> Result<(GatewayConfig, tempfile::TempDir), String> {
+    let directory = tempfile::tempdir().map_err(|error| error.to_string())?;
+    let deploy = directory.path().join("deploy");
+    fs::create_dir(&deploy).map_err(|error| error.to_string())?;
+    let path = deploy.join("config.yaml");
+    fs::write(&path, config).map_err(|error| error.to_string())?;
+    let mut config = config::Config::builder()
+        .add_source(config::File::from(path).required(true))
+        .build()
+        .and_then(config::Config::try_deserialize::<GatewayConfig>)
+        .map_err(|error| error.to_string())?;
+    config
+        .resolve_and_validate(&deploy)
+        .map_err(|error| error.to_string())?;
+    Ok((config, directory))
+}
+
+#[test]
+fn deployment_timezone_defaults_and_valid_override_are_loaded() {
+    let mut document = valid_config_document();
+    document["host"].as_object_mut().unwrap().remove("timezone");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Shanghai");
+    document["host"]["timezone"] = serde_json::json!("Asia/Kathmandu");
+    let (_config, _directory) = parse_config(&document.to_string()).unwrap();
+    let host: gateway_host::config::HostConfig =
+        serde_json::from_value(document["host"].clone()).unwrap();
+    assert_eq!(host.timezone.name(), "Asia/Kathmandu");
+}

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

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

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

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

backend/apps/gateway/tests/main.rs

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

backend/apps/plugin-cli/Cargo.toml

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

backend/apps/plugin-cli/README.md

@@ -0,0 +1,55 @@
+# Codex Proxy Plugin CLI
+
+`cpr-plugin` 校验并规范化作者清单、收集声明的资源，生成可安装归档及 SHA-256 校验文件。
+输出合同与 [SDK 版本](../../crates/gateway-plugin/sdk/README.md)一致
+
+## 安装
+
+从仓库根目录安装到本地工具目录：
+
+```bash
+cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
+```
+
+将 `/path/to/local-tools/bin` 加入 `PATH`，或使用可执行文件的完整路径；工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致
+
+## 打包
+
+先构建目标平台的二进制；有管理页面时，也构建静态资源。全部参数见 `cpr-plugin package --help`
+
+```bash
+cpr-plugin package \
+  --manifest /path/to/plugin/plugin.json \
+  --binary /path/to/plugin/target/x86_64-unknown-linux-gnu/release/plugin \
+  --target x86_64-unknown-linux-gnu \
+  --resource-map web=web/dist \
+  --output-dir /path/to/output
+```
+
+`--resource-map web=web/dist` 将包内 `web/` 前缀映射到作者清单所在目录下的 `web/dist/`。
+可重复传入不同前缀，源目录必须位于项目内；没有对应资源时省略该参数，未使用的映射会被拒绝。
+未映射的资源按清单中的相对路径读取，只收集 `resources` 声明的文件
+
+输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及同名 `.tar.gz.sha256`；归档根目录直接包含 `plugin.json`、可执行文件和声明资源。
+输入清单及生成后的清单均不得超过 64 KiB，压缩包上限为 32 MiB，展开归档上限为 128 MiB
+
+作者清单不填写 `package`；字段省略规则、能力版本和挂载阶段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)。
+CLI 生成规范化后的 `plugin.json`，补入协议版本、目标平台和文件摘要。打包成功只证明输入符合包合同，实际启动与能力仍需在目标宿主验证
+
+支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。
+完整开发示例在独立仓库 `codex-proxy-plugins` 的 `examples/workbench`，可通过[子模块](../../../docs/development.md#源码联调)检出；本工具不负责源码构建、上传或启用插件
+
+### 图标资源
+
+在作者清单的 `icon` 中指定图标，并在 `resources` 中登记对应路径与 MIME 类型，配置方式见
+[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算，
+无需额外命令参数；工具保留文件原始内容，宿主安装时验证图标内容与资源限制
+
+## 开发
+
+Rust 包名为 `codex-proxy-plugin-cli`，位于宿主的 `backend` workspace，共享工具链、锁文件和检查规则；内部仅依赖 `gateway-plugin-sdk`
+
+```bash
+cargo +1.99.1 run --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked -- package --help
+RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p codex-proxy-plugin-cli --locked
+```

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

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

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

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

backend/crates/gateway-admin/Cargo.toml

@@ -16,27 +16,33 @@ argon2 = "0.6.0"
 async-trait = "0.1.89"
 base64 = "0.23.0"
 bytes = "1.11.1"
-chrono = "0.4.45"
+chrono = { version = "0.4.45", features = ["serde"] }
 futures = "0.3.32"
 gateway-core = { path = "../gateway-core" }
+gateway-protocol = { path = "../gateway-protocol" }
 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"] }
 secrecy = { version = "0.10.3", features = ["serde"] }
+semver = "1.0.27"
+sha2 = "0.11"
 subtle = "2.6.1"
 thiserror = "2.0.18"
 tracing = "0.1.44"
-uuid = { version = "1.23.3", features = ["v7"] }
+uuid = { version = "1.23.3", features = ["v4", "v7"] }
 cron = "0.17"
 chrono-tz = "0.10"
 tokio = { version = "1.52", features = ["rt", "time", "macros", "sync"] }
 
 [dev-dependencies]
-sha2 = "0.11"
+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"] }
+tokio = { version = "1.52.3", default-features = false, features = ["macros", "rt", "test-util"] }
 
 [lints]
 workspace = true

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

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

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

@@ -1,6 +1,6 @@
-//! 备份纯策略：Cron 推进与保留候选。
+//! 备份纯策略：Cron 推进与保留候选
 //!
-//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集。
+//! 本模块不持有任何端口或对象，是 `BackupService` 与 `BackupTask` 共用的纯函数集
 
 use std::str::FromStr;
 
@@ -10,10 +10,11 @@ use cron::Schedule;
 
 use crate::model::backup::{BackupError, BackupRecord, BackupStatus, code};
 
-/// 向历史回溯的最大范围（分钟）。覆盖 Feb 29 + 特定星期等罕见组合的最长间隔。
+/// 向历史回溯的最大范围（分钟）
+/// 覆盖 Feb 29 + 特定星期等罕见组合的最长间隔
 const MAX_BACKDATE_MINUTES: i64 = 40 * 366 * 24 * 60;
 
-/// 已解析并校验的备份计划。
+/// 已解析并校验的备份计划
 #[derive(Debug, Clone)]
 pub struct BackupSchedule {
     schedule: Schedule,
@@ -21,43 +22,44 @@ pub struct BackupSchedule {
 }
 
 impl BackupSchedule {
-    /// 解析并校验 5 段 Cron 与 IANA 时区。
+    /// 按部署时区解析并校验 5 段 Cron
     ///
     /// # Errors
     ///
-    /// Cron 非法或时区不是 IANA 名称时返回 [`BackupError`]。
-    pub fn parse(cron_expression: &str, schedule_timezone: &str) -> Result<Self, BackupError> {
+    /// Cron 非法时返回 [`BackupError`]
+    pub fn parse(
+        cron_expression: &str,
+        timezone: gateway_core::time::DeploymentTimeZone,
+    ) -> Result<Self, BackupError> {
         let expression = format!("0 {cron_expression}");
         let schedule = Schedule::from_str(&expression).map_err(|_| {
             BackupError::new(code::INVALID_CRON, "Cron 表达式必须是 5 段格式".to_owned())
         })?;
-        let timezone = schedule_timezone.parse::<Tz>().map_err(|_| {
-            BackupError::new(code::INVALID_TIMEZONE, "时区必须是 IANA 名称".to_owned())
-        })?;
-        Ok(Self { schedule, timezone })
+        Ok(Self {
+            schedule,
+            timezone: timezone.iana(),
+        })
     }
 
-    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间。
+    /// 返回最接近 `at`（含 `at` 所在分钟）的最近一次触发时间
     ///
     /// 若过去 `MAX_BACKDATE_MINUTES` 内没有任何触发（极罕见的稀疏计划或超长停机），
-    /// 返回 `None`，调用方不应为历史点补任务。
+    /// 返回 `None`，调用方不应为历史点补任务
     #[must_use]
     pub fn last_firing_at_or_before(&self, at: DateTime<Utc>) -> Option<DateTime<Utc>> {
         let high_min = at.timestamp().div_euclid(60);
         let low_min = high_min.saturating_sub(MAX_BACKDATE_MINUTES);
 
-        // 检查窗口内是否存在触发；不存在则直接返回 None。
+        // 检查窗口内是否存在触发；不存在则直接返回 None
         let low_instant = instant(low_min, self.timezone)?;
         if self
-            .schedule
-            .after(&low_instant)
-            .next()
+            .next_after(low_instant.to_utc())
             .is_none_or(|firing| firing.timestamp() > high_min * 60 + 59)
         {
             return None;
         }
 
-        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)。
+        // 二分查找最小的 u（分钟）使 after(u) > high；prev = after(u - 1 分钟)
         let mut lo = low_min;
         let mut hi = high_min;
         while lo < hi {
@@ -76,76 +78,80 @@ 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` 由到期扫描处理
+/// - `offset` 是当前页在全部 completed 计划备份中的起始位置
 #[must_use]
 pub fn decide_retention(
     retention_days: u32,
     retention_count: u32,
     now: DateTime<Utc>,
+    offset: u64,
     scheduled_completed_desc: &[BackupRecord],
 ) -> Vec<RetentionDecision> {
     let mut decisions = Vec::new();
     for (index, record) in scheduled_completed_desc.iter().enumerate() {
+        let position = offset.saturating_add(index as u64);
         if record.status != BackupStatus::Completed {
             continue;
         }
-        // 最近一个成功的计划备份永远保留。
-        if index == 0 {
+        // 最近一个成功的计划备份永远保留
+        if position == 0 {
             continue;
         }
         let expired_by_days = retention_days > 0
             && record.completed_at.is_some_and(|completed_at| {
                 completed_at <= now - Duration::days(i64::from(retention_days))
             });
-        let exceeded_count =
-            retention_count > 0 && index >= usize::try_from(retention_count).unwrap_or(usize::MAX);
+        let exceeded_count = retention_count > 0 && position >= u64::from(retention_count);
         if expired_by_days || exceeded_count {
             decisions.push(RetentionDecision {
                 record_id: record.id.clone(),

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

@@ -1,7 +1,8 @@
-//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理。
+//! Backup Worker 贡献：单个可取消 `DaemonTask` 承担调度、执行、删除收敛与保留清理
 //!
-//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat。长时间
-//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭。
+//! 当前部署边界是单副本，因此不需要 Redis lease、fencing token 或 heartbeat
+//! 长时间
+//! `pg_dump` 与上传由本 Daemon 自身持有；Host 只负责 panic 后重启、健康与关闭
 
 use std::sync::Arc;
 use std::time::Duration;
@@ -10,14 +11,18 @@ use chrono::{DateTime, Utc};
 use futures::future::BoxFuture;
 use gateway_core::{
     lifecycle::CancellationToken,
-    task::{DaemonTask, WorkerTaskError},
+    task::{
+        DaemonRestartPolicy, DaemonTask, WorkerContribution, WorkerDaemonContext, WorkerId,
+        WorkerKind, WorkerRegistration, WorkerRunnable, WorkerTaskError,
+    },
 };
 use tracing::{info, warn};
 
 use crate::{
+    model::AdminError,
     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 +32,33 @@ 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 后该时长内生效；无工作时可取消等待。
+const BACKUP_WORKER_OWNER: &str = "backup";
+
+/// 循环间隔：管理员修改 Cron 后该时长内生效；无工作时可取消等待
 const BACKUP_LOOP_INTERVAL: Duration = Duration::from_secs(30);
-/// 每个循环最多执行的保留删除数量。
+/// 每个循环最多执行的保留删除数量
 const RETENTION_BATCH_SIZE: usize = 10;
-/// 保留扫描一次读取的 completed 计划备份上限。
-const RETENTION_SCAN_LIMIT: u32 = 1000;
-/// 每个循环最多完成的待删除记录数量。
+/// 保留扫描每页读取的 completed 计划备份数量
+const RETENTION_PAGE_SIZE: u32 = 1000;
+/// 每个循环最多完成的待删除记录数量
 const PENDING_DELETION_BATCH: u32 = 20;
 
-/// 备份 Daemon 任务。
+/// 备份 Daemon 任务
 pub struct BackupTask {
+    timezone: gateway_core::time::DeploymentTimeZone,
     repository: Arc<dyn BackupRepository>,
     dump: Arc<dyn DatabaseDumpPort>,
     object_store: Arc<dyn BackupObjectStorePort>,
 }
 
 impl BackupTask {
-    /// 组合仓储、导出器与对象存储适配器。
+    /// 组合仓储、导出器与对象存储适配器
     #[must_use]
     pub fn new(
         repository: Arc<dyn BackupRepository>,
@@ -58,26 +66,51 @@ 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
+    }
+
+    pub(crate) fn into_worker(self) -> Result<WorkerContribution, AdminError> {
+        let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
+            .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
+        let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
+            .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
+        let registration = WorkerRegistration::try_new(
+            id,
+            WorkerRunnable::Daemon {
+                restart,
+                task: Box::new(self),
+            },
+        )
+        .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
+        Ok(WorkerContribution::Registration(registration))
+    }
 }
 
 impl DaemonTask for BackupTask {
-    fn run(&self, cancellation: CancellationToken) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
-        Box::pin(async move { self.run_daemon(cancellation).await })
+    fn run(&self, context: WorkerDaemonContext) -> BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move { self.run_daemon(context).await })
     }
 }
 
 impl BackupTask {
-    async fn run_daemon(&self, cancellation: CancellationToken) -> Result<(), WorkerTaskError> {
+    async fn run_daemon(&self, context: WorkerDaemonContext) -> Result<(), WorkerTaskError> {
+        let cancellation = context.cancellation();
         loop {
             if cancellation.is_cancelled() {
                 return Ok(());
             }
-            self.run_cycle(&cancellation).await?;
+            self.run_cycle(cancellation).await?;
+            context.succeeded();
 
             tokio::select! {
                 _ = cancellation.cancelled() => return Ok(()),
@@ -86,13 +119,13 @@ impl BackupTask {
         }
     }
 
-    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理。
+    /// 执行一个周期：推进计划、恢复中间态、删除收敛、领取执行一个任务、保留清理
     ///
-    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用。
+    /// 对外暴露以便集成测试逐周期驱动；daemon 循环内部复用
     ///
     /// # Errors
     ///
-    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]。
+    /// 仓储或基础设施不可用、任务执行失败时返回 [`WorkerTaskError`]
     pub async fn run_cycle(&self, cancellation: &CancellationToken) -> Result<(), WorkerTaskError> {
         if cancellation.is_cancelled() {
             return Ok(());
@@ -101,33 +134,56 @@ impl BackupTask {
         self.recover_intermediate(cancellation).await?;
         self.finish_pending_deletions().await?;
         self.process_next_task(cancellation).await?;
-        self.run_retention_batch(Utc::now()).await?;
+        self.run_retention_batch(Utc::now(), cancellation).await?;
         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 +197,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 +230,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 +267,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败。
+    /// dumping：有完整暂存则继续上传，否则清理暂存并标记失败
     async fn recover_dumping(
         &self,
         record: &BackupRecord,
@@ -224,8 +285,7 @@ impl BackupTask {
                     .repository
                     .transition_status(
                         &record.id,
-                        BackupStatus::Dumping,
-                        BackupStatus::Uploading,
+                        status_transition(BackupStatus::Dumping, BackupStatus::Uploading)?,
                         update,
                         now,
                     )
@@ -245,7 +305,6 @@ impl BackupTask {
                 .await?;
             }
             None => {
-                let _ = self.dump.cleanup_staging(&record.id).await;
                 self.fail_task(record, code::PG_DUMP_FAILED, "导出进程中断，暂存归档不完整")
                     .await?;
             }
@@ -253,7 +312,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败。
+    /// uploading：远端匹配则补记完成，有完整暂存则重试上传，否则失败
     async fn recover_uploading(
         &self,
         record: &BackupRecord,
@@ -271,16 +330,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 +369,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 +396,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 领取一个 queued 任务并执行导出、上传与远端校验。
+    /// 领取一个 queued 任务并执行导出、上传与远端校验
     async fn process_next_task(
         &self,
         cancellation: &CancellationToken,
@@ -358,7 +421,7 @@ impl BackupTask {
         Ok(())
     }
 
-    /// 执行单个任务；内部处理全部状态迁移。
+    /// 执行单个任务；内部处理全部状态迁移
     async fn execute_task(
         &self,
         record: &BackupRecord,
@@ -392,7 +455,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 +465,7 @@ impl BackupTask {
             .repository
             .transition_status(
                 &record.id,
-                BackupStatus::Dumping,
-                BackupStatus::Uploading,
+                status_transition(BackupStatus::Dumping, BackupStatus::Uploading)?,
                 update,
                 now,
             )
@@ -421,12 +483,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 +515,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 +533,7 @@ impl BackupTask {
                     .repository
                     .transition_status(
                         &record.id,
-                        BackupStatus::Uploading,
-                        BackupStatus::Completed,
+                        status_transition(BackupStatus::Uploading, BackupStatus::Completed)?,
                         StatusTransitionUpdate::default(),
                         Utc::now(),
                     )
@@ -485,6 +546,7 @@ impl BackupTask {
                         size_bytes,
                         "备份完成"
                     );
+                    self.cleanup_staging(&record.id).await;
                 }
             }
             Ok(Some(remote)) => {
@@ -497,16 +559,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 +585,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 +599,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 +640,33 @@ 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 run_retention_batch(&self, now: DateTime<Utc>) -> Result<(), WorkerTaskError> {
+    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>,
+        cancellation: &CancellationToken,
+    ) -> 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)
@@ -575,7 +675,7 @@ impl BackupTask {
         for record in expired {
             let Some(record) = self
                 .repository
-                .transition_to_deleting(&record.id, now)
+                .transition_to_deleting(&record.id, now, None)
                 .await
                 .map_err(repo_error)?
             else {
@@ -584,22 +684,45 @@ impl BackupTask {
             self.finalize_deletion(&record).await?;
         }
 
-        // 2. 计划备份按 retentionDays / retentionCount 清理。
-        let records = self
-            .repository
-            .list_scheduled_completed_desc(RETENTION_SCAN_LIMIT)
-            .await
-            .map_err(repo_error)?;
-        let decisions = decide_retention(
-            settings.retention_days,
-            settings.retention_count,
-            now,
-            &records,
-        );
-        for decision in decisions.into_iter().take(RETENTION_BATCH_SIZE) {
+        // 2. 计划备份按 retentionDays / retentionCount 清理
+        if settings.retention_days == 0 && settings.retention_count == 0 {
+            return Ok(());
+        }
+        let mut offset = 0;
+        let mut decisions = Vec::new();
+        loop {
+            if cancellation.is_cancelled() {
+                return Ok(());
+            }
+            let records = self
+                .repository
+                .list_scheduled_completed_desc(offset, RETENTION_PAGE_SIZE)
+                .await
+                .map_err(repo_error)?;
+            let remaining = RETENTION_BATCH_SIZE - decisions.len();
+            decisions.extend(
+                decide_retention(
+                    settings.retention_days,
+                    settings.retention_count,
+                    now,
+                    offset,
+                    &records,
+                )
+                .into_iter()
+                .take(remaining),
+            );
+            if decisions.len() == RETENTION_BATCH_SIZE
+                || records.len() < RETENTION_PAGE_SIZE as usize
+            {
+                break;
+            }
+            offset += records.len() as u64;
+        }
+        // 收齐本批候选后再删除，避免删除前页记录导致后续分页跳过数据
+        for decision in decisions {
             let Some(record) = self
                 .repository
-                .transition_to_deleting(&decision.record_id, now)
+                .transition_to_deleting(&decision.record_id, now, None)
                 .await
                 .map_err(repo_error)?
             else {
@@ -610,7 +733,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 {
@@ -634,15 +757,27 @@ impl BackupTask {
 fn classify_dump_error(error: BackupError) -> (&'static str, &'static str) {
     match error.code() {
         code::CANCELLED => (code::CANCELLED, "备份已取消"),
+        code::ANALYTICS_NOT_READY => (
+            code::ANALYTICS_NOT_READY,
+            "用量统计正在重建，请在统计就绪后重试备份",
+        ),
         code::STAGING_SPACE_EXHAUSTED => (code::STAGING_SPACE_EXHAUSTED, "暂存磁盘空间不足"),
         _ => (code::PG_DUMP_FAILED, "数据库导出失败"),
     }
 }
 
+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)
 }

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

@@ -0,0 +1,341 @@
+//! 管理服务与后台任务的启动组装，窄端口供服务器和 CLI 复用
+
+use std::{path::Path, sync::Arc};
+
+use gateway_core::{engine::probe::AccountProbe, runtime::SnapshotControl};
+
+use crate::{
+    AccountsService, AdminBundle, AdminConfig, AdminRuntimePorts, AdminServices, ClientConfig,
+    ClientKeyService, CredentialsService, PluginDistributionPorts, PluginManagementService,
+    PluginsService, SettingsService, UsageDataService, backup, freeze_recovery,
+    model::AdminError,
+    ports::{
+        self, plugin_accounts::PluginAccountAccess, plugin_client_keys::PluginClientKeyAccess,
+        provider::ProviderAdminRegistry, store::AdminStorePorts,
+    },
+    public_service, reset_credit_worker, use_case,
+    use_case::{
+        account_groups::DefaultAccountGroupService,
+        accounts::DefaultAccountsService,
+        auth::{AuthService, DefaultAuthService},
+        backup::DefaultBackupService,
+        client_distribution::DefaultClientDistributionService,
+        client_keys::DefaultClientKeyService,
+        observability::DefaultObservabilityService,
+        settings::DefaultSettingsService,
+        system::DefaultSystemService,
+    },
+};
+
+/// 校验配置、接入已组装的 Provider 注册表并完成默认管理员幂等初始化
+///
+/// # Errors
+///
+/// 配置非法或默认管理员初始化失败时返回错误
+pub async fn initialize(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, None).await
+}
+
+/// 使用组合根已绑定给 Runtime 的同一账号窄端口，避免为完整 Admin 重建第二实例
+pub async fn initialize_with_plugin_accounts(
+    config: AdminConfig,
+    client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+    plugin_accounts: Arc<dyn PluginAccountAccess>,
+) -> Result<AdminBundle, AdminError> {
+    initialize_inner(config, client_config, store, runtime, Some(plugin_accounts)).await
+}
+
+async fn initialize_inner(
+    mut config: AdminConfig,
+    mut client_config: ClientConfig,
+    store: AdminStorePorts,
+    runtime: AdminRuntimePorts,
+    plugin_accounts: Option<Arc<dyn PluginAccountAccess>>,
+) -> Result<AdminBundle, AdminError> {
+    let AdminRuntimePorts {
+        upstream_info,
+        timezone,
+        service_middleware,
+        plugin_preparation,
+        plugin_management,
+        published_snapshot,
+        plugin_distribution,
+        plugin_inspector,
+        pricing_source,
+        providers,
+        snapshot,
+        account_probe: probe,
+        proxy_probe,
+        client_distribution,
+        system,
+        client_key_verifier,
+    } = runtime;
+    config
+        .resolve_and_validate(Path::new("."))
+        .map_err(|error| AdminError::invalid(error.to_string()))?;
+    client_config
+        .resolve_and_validate(Path::new("."))
+        .map_err(|error| AdminError::invalid(error.to_string()))?;
+
+    let auth = Arc::new(DefaultAuthService::new(
+        &config,
+        client_config.session_ttl_minutes,
+        store.auth(),
+        client_key_verifier.clone(),
+    ));
+    auth.ensure_default_admin(config.default_password.expose())
+        .await?;
+
+    let accounts = initialize_accounts(
+        store.accounts(),
+        store.account_runtime(),
+        store.settings(),
+        timezone,
+        providers.clone(),
+        snapshot.clone(),
+        probe.clone(),
+        upstream_info.clone(),
+    );
+    let backup_ports = store.backup();
+    let backups = Arc::new(DefaultBackupService::new(
+        backup_ports.repository(),
+        backup_ports.object_store(),
+        store.auth(),
+        snapshot.clone(),
+        timezone,
+    ));
+    let backup_task = backup::task::BackupTask::new(
+        backup_ports.repository(),
+        backup_ports.dump(),
+        backup_ports.object_store(),
+    )
+    .with_timezone(timezone);
+    let system_preflight = Arc::new(
+        use_case::system_preflight::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(),
+        observations.clone(),
+        system.clone(),
+        timezone,
+    ));
+    let credentials = Arc::new(CredentialsService::new(
+        providers.clone(),
+        store.accounts(),
+        store.proxies(),
+        snapshot.clone(),
+        upstream_info.clone(),
+    ));
+    let plugin_accounts = plugin_accounts.unwrap_or_else(|| {
+        initialize_plugin_accounts(
+            providers.clone(),
+            store.accounts(),
+            snapshot.clone(),
+            upstream_info.clone(),
+        )
+    });
+    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(),
+        providers.clone(),
+        pricing_source,
+    );
+    let usage_data = initialize_usage_data(store.usage_data(), store.settings(), providers.clone());
+    let mut public_services = public_service::Registry::new(service_middleware);
+    public_services.register_settings(&settings)?;
+    public_services.register_accounts(&accounts)?;
+    public_services.register_usage_data(&usage_data)?;
+    let services = AdminServices {
+        peer_link: Arc::new(use_case::peer_link::DefaultPeerLinkService::new(
+            store.client_keys(),
+            store.accounts(),
+            store.account_runtime(),
+            providers.clone(),
+        )),
+        timezone,
+        public_services: Arc::new(public_services),
+        plugin_management: Arc::new(PluginManagementService::new(
+            plugin_management,
+            store.plugins(),
+            published_snapshot.clone(),
+        )),
+        plugins: Arc::new(PluginsService::new(
+            store.plugins(),
+            plugin_inspector,
+            PluginDistributionPorts::new(plugin_distribution, store.proxies()),
+            snapshot.clone(),
+            plugin_preparation,
+            published_snapshot,
+            store.plugin_state(),
+        )),
+        key_usage,
+        proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
+            store.proxies(),
+            proxy_probe,
+            snapshot.clone(),
+            providers.clone(),
+            upstream_info.clone(),
+        )),
+        auth,
+        accounts: accounts.clone(),
+        account_groups: Arc::new(DefaultAccountGroupService::new(
+            upstream_info.clone(),
+            store.account_groups(),
+            store.account_runtime(),
+            snapshot.clone(),
+        )),
+        client_keys: Arc::new(DefaultClientKeyService::new(
+            store.client_keys(),
+            snapshot.clone(),
+            providers.clone(),
+        )),
+        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
+        observability: Arc::new(DefaultObservabilityService::new(
+            observations.clone(),
+            store.accounts(),
+            store.settings(),
+            providers.clone(),
+            timezone,
+            system.clone(),
+            upstream_info,
+        )),
+        settings,
+        usage_data,
+        system,
+        credentials,
+        _plugin_accounts: plugin_accounts,
+        import_tasks,
+        backups,
+    };
+    let freeze_recovery =
+        freeze_recovery::FreezeRecoveryTask::new(freeze_recovery::FreezeRecoveryDeps {
+            accounts: Arc::clone(&accounts) as Arc<dyn AccountsService>,
+            store: store.accounts(),
+            runtime: store.account_runtime(),
+            settings: store.settings(),
+        });
+    let worker_contributions = vec![
+        backup_task.into_worker()?,
+        import_task.into_worker()?,
+        freeze_recovery.into_worker()?,
+        reset_credit_worker::ResetCreditAutomationTask {
+            accounts,
+            store: store.accounts(),
+            settings: store.settings(),
+        }
+        .into_worker()?,
+    ];
+    Ok(AdminBundle {
+        services,
+        worker_contributions,
+    })
+}
+
+/// CLI 只组合账号用例，不初始化管理员、管理服务或后台任务；写入仍复用同一事务与审计
+pub fn initialize_plugin_accounts(
+    providers: ports::provider::ProviderAdminRegistry,
+    accounts: Arc<dyn ports::store::AccountStore>,
+    snapshot: Arc<dyn gateway_core::runtime::SnapshotControl>,
+    upstream_info: Option<Arc<dyn ports::peer::PeerUpstreamService>>,
+) -> Arc<dyn PluginAccountAccess> {
+    Arc::new(use_case::plugin_accounts::DefaultPluginAccountAccess::new(
+        providers,
+        accounts,
+        snapshot,
+        upstream_info,
+    ))
+}
+
+/// 为 Runtime 创建非秘密 Client Key 目录与预算重置的窄端口
+#[must_use]
+pub fn initialize_plugin_client_keys(
+    providers: ports::provider::ProviderAdminRegistry,
+    store: Arc<dyn ports::store::ClientKeyStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+) -> Arc<dyn PluginClientKeyAccess> {
+    let service: Arc<dyn ClientKeyService> =
+        Arc::new(DefaultClientKeyService::new(store, snapshot, providers));
+    Arc::new(use_case::plugin_client_keys::DefaultPluginClientKeyAccess::new(service))
+}
+
+/// 为 Runtime 组合实例自有资源写入；权限和归属在同一存储事务复核
+#[must_use]
+pub fn initialize_plugin_resources(
+    store: Arc<dyn ports::plugin_resources::PluginResourceStore>,
+    snapshot: Arc<dyn SnapshotControl>,
+) -> Arc<dyn ports::plugin_resources::PluginResourceAccess> {
+    Arc::new(use_case::plugin_resources::DefaultPluginResourceAccess { store, snapshot })
+}
+
+/// 服务端与 CLI 复用账号用例，不随命令启动后台调度
+#[must_use]
+#[expect(
+    clippy::too_many_arguments,
+    reason = "账号存储、发布、探测与互联分别通过独立端口注入"
+)]
+pub fn initialize_accounts(
+    accounts: Arc<dyn ports::store::AccountStore>,
+    account_runtime: Arc<dyn ports::store::AccountRuntimeStore>,
+    settings: Arc<dyn ports::store::SettingsStore>,
+    timezone: gateway_core::time::DeploymentTimeZone,
+    providers: ProviderAdminRegistry,
+    snapshot: Arc<dyn SnapshotControl>,
+    probe: Arc<dyn AccountProbe>,
+    upstream_info: Option<Arc<dyn ports::peer::PeerUpstreamService>>,
+) -> Arc<dyn AccountsService> {
+    Arc::new(DefaultAccountsService::new(
+        accounts,
+        account_runtime,
+        settings,
+        timezone,
+        providers,
+        snapshot,
+        probe,
+        upstream_info,
+    ))
+}
+
+/// 设置服务不依赖 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,
+    ))
+}
+
+/// HTTP、插件及 CLI 共用的用量领域用例，宿主提供已验证的调用主体
+#[must_use]
+pub fn initialize_usage_data(
+    store: Arc<dyn ports::usage_data::UsageDataStore>,
+    settings: Arc<dyn ports::store::SettingsStore>,
+    providers: ProviderAdminRegistry,
+) -> Arc<dyn UsageDataService> {
+    Arc::new(use_case::usage_data::DefaultUsageDataService::new(
+        store, settings, providers,
+    ))
+}

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

@@ -0,0 +1,286 @@
+//! 账号错误保护的到期探测与按冻结快照恢复
+
+use std::collections::BTreeMap;
+use std::sync::Arc;
+use std::time::{Duration, SystemTime};
+
+use chrono::{DateTime, Utc};
+use futures::StreamExt as _;
+use gateway_core::account::{AccountErrorProtection, ProviderAccountId};
+use gateway_core::engine::probe::AccountProbeTarget;
+use gateway_core::routing::UpstreamModelId;
+use gateway_core::task::{
+    ScheduledTask, WorkerContribution, WorkerCycleContext, WorkerId, WorkerKind,
+    WorkerLeaseRequest, WorkerRegistration, WorkerRunnable, WorkerSchedule, WorkerTaskError,
+};
+use tracing::warn;
+
+use crate::model::AdminError;
+use crate::model::accounts::{
+    AccountConnectionTestEvent, AccountFreeze, AccountPageItem, AccountRuntimeSnapshot,
+};
+use crate::ports::store::{AccountRuntimeStore, AccountStore, SettingsStore};
+use crate::use_case::accounts::AccountsService;
+
+/// 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);
+/// 冻结恢复所需的管理端口组合
+#[derive(Clone)]
+pub struct FreezeRecoveryDeps {
+    pub accounts: Arc<dyn AccountsService>,
+    pub store: Arc<dyn AccountStore>,
+    pub runtime: Arc<dyn AccountRuntimeStore>,
+    pub settings: Arc<dyn SettingsStore>,
+}
+
+pub struct FreezeRecoveryTask {
+    deps: FreezeRecoveryDeps,
+}
+
+impl FreezeRecoveryTask {
+    pub fn new(deps: FreezeRecoveryDeps) -> Self {
+        Self { deps }
+    }
+
+    pub(crate) fn into_worker(self) -> Result<WorkerContribution, AdminError> {
+        let id = WorkerId::try_new(
+            WorkerKind::AccountFreezeRecovery,
+            FREEZE_RECOVERY_WORKER_OWNER,
+        )
+        .map_err(|_| AdminError::internal("冻结恢复 Worker ID 不合法"))?;
+        let schedule = WorkerSchedule::try_new(
+            FREEZE_RECOVERY_INTERVAL,
+            WORKER_INITIAL_BACKOFF,
+            WORKER_MAXIMUM_BACKOFF,
+            WORKER_LEASE_TTL,
+            WORKER_LEASE_RENEWAL,
+        )
+        .map_err(|_| AdminError::internal("冻结恢复 Worker 调度配置不合法"))?;
+        let lease = WorkerLeaseRequest::try_new(id.clone(), WORKER_LEASE_TTL)
+            .map_err(|_| AdminError::internal("冻结恢复 Worker 租约配置不合法"))?;
+        let registration = WorkerRegistration::try_new(
+            id,
+            WorkerRunnable::Scheduled {
+                schedule,
+                lease: Some(lease),
+                task: Box::new(self),
+            },
+        )
+        .map_err(|_| AdminError::internal("冻结恢复 Worker 注册信息不合法"))?;
+        Ok(WorkerContribution::Registration(registration))
+    }
+
+    /// 无法读取或校验配置时跳过本轮，不能把未知状态当作允许解冻
+    async fn freeze_policy(&self) -> Option<AccountErrorProtection> {
+        let settings = self.deps.settings.load_runtime_settings().await.ok()?;
+        let policy = settings.values.account_error_protection;
+        policy.validate().ok()?;
+        Some(policy)
+    }
+
+    async fn active_freezes(&self) -> BTreeMap<String, AccountFreeze> {
+        self.deps.runtime.active_freezes().await.unwrap_or_default()
+    }
+
+    async fn run_cycle_inner(&self) {
+        let Some(policy) = self.freeze_policy().await else {
+            return;
+        };
+        let freezes = self.active_freezes().await;
+        if freezes.is_empty() {
+            return;
+        }
+        self.recover_due_freezes(&freezes, &policy).await;
+    }
+
+    async fn load_account(&self, account_id: &str) -> Option<Option<AccountPageItem>> {
+        let account_id = ProviderAccountId::new(account_id.to_owned()).ok()?;
+        self.deps
+            .store
+            .load_account(account_id.as_str(), AccountRuntimeSnapshot::default())
+            .await
+            .ok()
+    }
+
+    /// 到达探测时间后才恢复；关闭自动冻结或探测时，已有冻结仍等待原冷却结束
+    async fn recover_due_freezes(
+        &self,
+        freezes: &BTreeMap<String, AccountFreeze>,
+        policy: &AccountErrorProtection,
+    ) {
+        for (account_id, freeze) in freezes {
+            if freeze.until > Utc::now() {
+                continue;
+            }
+            if policy.enabled && policy.probe_enabled && freeze.requires_probe {
+                self.probe_and_recover(account_id, freeze, policy).await;
+            } else if let Err(error) = self
+                .deps
+                .runtime
+                .finish_freeze(account_id, freeze, None)
+                .await
+            {
+                warn!(account_id, error = %error, "解除到期冻结失败");
+            }
+        }
+    }
+
+    async fn probe_and_recover(
+        &self,
+        account_id: &str,
+        freeze: &AccountFreeze,
+        policy: &AccountErrorProtection,
+    ) {
+        let Some(Some(item)) = self.load_account(account_id).await else {
+            return;
+        };
+        if item.account.credential_revision != freeze.credential_revision {
+            let _ = self
+                .deps
+                .runtime
+                .finish_freeze(account_id, freeze, None)
+                .await;
+            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, freeze, policy).await else {
+            // 没有可用探测模型时按失败处理，顺延冻结等待下一轮
+            self.postpone(&account, freeze, policy).await;
+            return;
+        };
+        let probe_succeeded = match self
+            .deps
+            .accounts
+            .test_connection(AccountProbeTarget::FreezeRecovery(account.clone()), model)
+            .await
+        {
+            Ok(events) => drain_probe(events).await,
+            Err(error) => {
+                tracing::debug!(account_id, error = %error, "冻结恢复探测发起失败");
+                false
+            }
+        };
+        if probe_succeeded {
+            match self
+                .deps
+                .runtime
+                .finish_freeze(account_id, freeze, None)
+                .await
+            {
+                Ok(true) => tracing::info!(account_id, "冻结恢复探测成功：账号已解冻"),
+                Ok(false) => {}
+                Err(error) => warn!(account_id, error = %error, "解除冻结失败"),
+            }
+        } else {
+            self.postpone(&account, freeze, policy).await;
+        }
+    }
+
+    /// 探测失败只顺延本次仍存在的冻结，旧探测不能重新冻结已手动恢复的账号
+    async fn postpone(
+        &self,
+        account: &ProviderAccountId,
+        freeze: &AccountFreeze,
+        policy: &AccountErrorProtection,
+    ) {
+        // 探测期间关闭保护或探测时，不再把已经到期的冻结向后延长
+        let Some(current) = self.freeze_policy().await else {
+            return;
+        };
+        if !current.enabled || !current.probe_enabled {
+            let _ = self
+                .deps
+                .runtime
+                .finish_freeze(account.as_str(), freeze, None)
+                .await;
+            return;
+        }
+        let Some(until) = SystemTime::now().checked_add(Duration::from_secs(
+            freeze.duration_seconds.unwrap_or(policy.duration_seconds),
+        )) else {
+            return;
+        };
+        let until = DateTime::<Utc>::from(until);
+        match self
+            .deps
+            .runtime
+            .finish_freeze(account.as_str(), freeze, Some(until))
+            .await
+        {
+            Ok(true) => {
+                tracing::info!(
+                    account_id = account.as_str(),
+                    postpone_seconds = Duration::from_secs(
+                        freeze.duration_seconds.unwrap_or(policy.duration_seconds)
+                    )
+                    .as_secs(),
+                    "冻结恢复探测失败：账号冻结顺延",
+                );
+            }
+            Ok(false) => {}
+            Err(error) => {
+                warn!(
+                    account_id = account.as_str(),
+                    error = %error,
+                    "冻结顺延失败"
+                );
+            }
+        }
+    }
+
+    async fn resolve_probe_model(
+        &self,
+        account: &ProviderAccountId,
+        freeze: &AccountFreeze,
+        policy: &AccountErrorProtection,
+    ) -> Option<UpstreamModelId> {
+        if let Some(model) = if freeze.duration_seconds.is_some() {
+            freeze.probe_model.as_deref()
+        } else {
+            policy.probe_model.as_deref()
+        } {
+            return UpstreamModelId::new(model.to_owned()).ok();
+        }
+        let models = self.deps.accounts.models(account, false).await.ok()?;
+        models.models.into_iter().next().map(|model| model.id)
+    }
+}
+
+impl ScheduledTask for FreezeRecoveryTask {
+    fn run_cycle(
+        &self,
+        context: WorkerCycleContext,
+    ) -> futures::future::BoxFuture<'_, Result<(), WorkerTaskError>> {
+        Box::pin(async move {
+            if context.cancellation().is_cancelled() {
+                return Ok(());
+            }
+            self.run_cycle_inner().await;
+            Ok(())
+        })
+    }
+}
+
+/// 消耗连接测试事件流并返回是否以 `Completed` 终止
+async fn drain_probe(mut events: crate::model::accounts::AccountConnectionTestEventStream) -> bool {
+    let mut completed = false;
+    while let Some(event) = events.next().await {
+        match event {
+            AccountConnectionTestEvent::Completed => completed = true,
+            AccountConnectionTestEvent::Failed { .. } => return false,
+            _ => {}
+        }
+    }
+    completed
+}

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

@@ -1,52 +1,58 @@
-//! 管理控制面的语义模型、用例与外部能力端口。
+//! 管理控制面的语义模型、用例与外部能力端口
 //!
-//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现。
+//! 本 crate 不包含 HTTP wire、数据库实现或具体 Provider 实现
 
-use std::{fmt, path::Path, sync::Arc, time::Duration};
+use std::{fmt, path::Path, sync::Arc};
 
 use gateway_core::{
-    engine::probe::AccountProbe,
-    routing::ProviderKind,
-    runtime::SnapshotControl,
-    task::{
-        DaemonRestartPolicy, WorkerContribution, WorkerId, WorkerKind, WorkerRegistration,
-        WorkerRunnable,
-    },
+    engine::execution::ClientKeyVerifier, engine::probe::AccountProbe, runtime::SnapshotControl,
+    task::WorkerContribution,
 };
 use secrecy::{ExposeSecret as _, SecretString};
 use serde::Deserialize;
 
 pub mod backup;
+mod bootstrap;
+pub mod freeze_recovery;
 pub mod model;
 pub mod ports;
+pub mod public_service;
+mod reset_credit_worker;
 mod use_case;
+pub use use_case::plugins::{PluginDistributionPorts, PluginManagementService, PluginsService};
+
+pub use use_case::key_usage::KeyUsageService;
+pub use use_case::peer_link::{PeerLinkError, PeerLinkService};
 
 pub use use_case::{
-    account_groups::AccountGroupService, accounts::AccountsService, auth::AuthService,
-    backup::BackupService, client_distribution::ClientDistributionService,
-    client_keys::ClientKeyService, observability::ObservabilityService, openai::OpenAiService,
-    proxies::ProxiesService, settings::SettingsService, system::SystemService, xai::XaiService,
+    account_groups::AccountGroupService,
+    accounts::AccountsService,
+    auth::AuthService,
+    backup::BackupService,
+    client_distribution::ClientDistributionService,
+    client_keys::ClientKeyService,
+    credentials::{CredentialsService, ProviderCredentials},
+    import_tasks::ImportTasksService,
+    observability::{ObservabilityService, ProviderUsageBillingProjector},
+    proxies::ProxiesService,
+    settings::SettingsService,
+    system::SystemService,
+    usage_data::UsageDataService,
+};
+
+pub use bootstrap::{
+    initialize, initialize_accounts, initialize_plugin_accounts, initialize_plugin_client_keys,
+    initialize_plugin_resources, initialize_settings, initialize_usage_data,
+    initialize_with_plugin_accounts,
 };
 
-use model::{AdminError, AdminErrorKind};
 use ports::{
-    client_distribution::ClientDistributionResolver,
-    provider::{ProviderAdmin, ProviderAdminError, ProviderAdminErrorKind, ProviderAdminRegistry},
-    store::AdminStorePorts,
-    system::SystemOperations,
-};
-use use_case::{
-    account_groups::DefaultAccountGroupService, accounts::DefaultAccountsService,
-    auth::DefaultAuthService, backup::DefaultBackupService,
-    client_distribution::DefaultClientDistributionService, client_keys::DefaultClientKeyService,
-    observability::DefaultObservabilityService, openai::DefaultOpenAiService,
-    settings::DefaultSettingsService, system::DefaultSystemService, xai::DefaultXaiService,
+    client_distribution::ClientDistributionResolver, plugin_accounts::PluginAccountAccess,
+    provider::ProviderAdminRegistry, system::SystemOperations,
 };
 
-const OPENAI_PROVIDER_KIND: &str = "openai";
-const XAI_PROVIDER_KIND: &str = "xai";
 const MINIMUM_INITIAL_PASSWORD_BYTES: usize = 12;
-const WEAK_INITIAL_PASSWORDS: &[&str] = &[
+const WEAK_ADMIN_PASSWORDS: &[&str] = &[
     "",
     "admin",
     "123456",
@@ -57,9 +63,9 @@ const WEAK_INITIAL_PASSWORDS: &[&str] = &[
     "codex-proxy-rs",
 ];
 
-const BACKUP_WORKER_OWNER: &str = "backup";
+const DEFAULT_CLIENT_SESSION_TTL_MINUTES: u64 = 24 * 60;
 
-/// 只用于首次幂等创建默认管理员的启动密码。
+/// 只用于首次幂等创建默认管理员的启动密码
 #[derive(Clone, Deserialize)]
 #[serde(transparent)]
 pub struct InitialAdminPassword(SecretString);
@@ -89,21 +95,54 @@ impl fmt::Debug for InitialAdminPassword {
     }
 }
 
-/// 管理控制面的启动配置。
+/// 管理控制面的启动配置
 #[derive(Clone, Deserialize, PartialEq, Eq)]
-#[serde(deny_unknown_fields)]
 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,
 }
 
-impl AdminConfig {
-    /// 校验 Admin-owned 字段；当前配置不含相对路径。
+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,
+}
+
+impl Default for ClientConfig {
+    fn default() -> Self {
+        Self {
+            session_ttl_minutes: DEFAULT_CLIENT_SESSION_TTL_MINUTES,
+        }
+    }
+}
+
+impl ClientConfig {
+    /// 校验 Client session TTL；当前配置不含相对路径
     ///
     /// # Errors
     ///
-    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误。
+    /// 会话有效期为零或无法安全换算时返回错误
+    pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
+        if self.session_ttl_minutes == 0 || i64::try_from(self.session_ttl_minutes).is_err() {
+            return Err(AdminConfigError::InvalidField("client.session_ttl_minutes"));
+        }
+        Ok(())
+    }
+}
+
+impl AdminConfig {
+    /// 校验 Admin-owned 字段；当前配置不含相对路径
+    ///
+    /// # Errors
+    ///
+    /// 用户名、会话有效期或初始密码不满足安全约束时返回错误
     pub fn resolve_and_validate(&mut self, _source_dir: &Path) -> Result<(), AdminConfigError> {
         if self.default_username.trim().is_empty()
             || self.default_username.chars().any(char::is_control)
@@ -113,10 +152,17 @@ 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('$')
-            || WEAK_INITIAL_PASSWORDS.contains(&password.to_ascii_lowercase().as_str())
+            || WEAK_ADMIN_PASSWORDS.contains(&password.to_ascii_lowercase().as_str())
         {
             return Err(AdminConfigError::WeakInitialPassword);
         }
@@ -129,13 +175,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}` 不合法")]
@@ -144,26 +194,69 @@ 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>,
     auth: Arc<dyn AuthService>,
+    key_usage: Arc<dyn KeyUsageService>,
+    peer_link: Arc<dyn PeerLinkService>,
     accounts: Arc<dyn AccountsService>,
     account_groups: Arc<dyn AccountGroupService>,
     client_keys: Arc<dyn ClientKeyService>,
     client_distribution: Arc<dyn ClientDistributionService>,
     observability: Arc<dyn ObservabilityService>,
     settings: Arc<dyn SettingsService>,
+    usage_data: Arc<dyn UsageDataService>,
     system: Arc<dyn SystemService>,
-    openai: Arc<dyn OpenAiService>,
-    xai: Arc<dyn XaiService>,
+    credentials: Arc<CredentialsService>,
+    // 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
+    }
+
+    #[must_use]
+    pub fn plugins(&self) -> &PluginsService {
+        &self.plugins
+    }
+
+    #[must_use]
+    pub fn import_tasks(&self) -> &dyn ImportTasksService {
+        self.import_tasks.as_ref()
+    }
+
+    #[must_use]
+    pub fn key_usage(&self) -> &dyn KeyUsageService {
+        self.key_usage.as_ref()
+    }
+
+    #[must_use]
+    pub fn peer_link(&self) -> &dyn PeerLinkService {
+        self.peer_link.as_ref()
+    }
+
     #[must_use]
     pub fn proxies(&self) -> &dyn ProxiesService {
         self.proxies.as_ref()
@@ -194,12 +287,16 @@ impl AdminServices {
         self.client_distribution.as_ref()
     }
 
+    #[must_use]
+    pub fn usage_data(&self) -> Arc<dyn UsageDataService> {
+        self.usage_data.clone()
+    }
+
     #[must_use]
     pub fn observability(&self) -> &dyn ObservabilityService {
         self.observability.as_ref()
     }
 
-    #[must_use]
     pub fn settings(&self) -> &dyn SettingsService {
         self.settings.as_ref()
     }
@@ -210,13 +307,8 @@ impl AdminServices {
     }
 
     #[must_use]
-    pub fn openai(&self) -> &dyn OpenAiService {
-        self.openai.as_ref()
-    }
-
-    #[must_use]
-    pub fn xai(&self) -> &dyn XaiService {
-        self.xai.as_ref()
+    pub fn credentials(&self) -> &CredentialsService {
+        self.credentials.as_ref()
     }
 
     #[must_use]
@@ -225,7 +317,7 @@ impl AdminServices {
     }
 }
 
-/// Admin 初始化完成后的封闭能力包。
+/// Admin 初始化完成后的封闭能力包
 pub struct AdminBundle {
     services: AdminServices,
     worker_contributions: Vec<WorkerContribution>,
@@ -237,152 +329,32 @@ impl AdminBundle {
         self.services.clone()
     }
 
-    /// 取出 Backup Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host。
+    /// 取出 Admin Worker 贡献；只能调用一次，与其它 Bundle 的贡献一并交给 Host
     pub fn take_worker_contributions(&mut self) -> Vec<WorkerContribution> {
         std::mem::take(&mut self.worker_contributions)
     }
 }
 
-/// 校验配置、建立动态 Provider 注册表并完成默认管理员幂等初始化。
-///
-/// # Errors
-///
-/// 配置非法、Provider 注册冲突/缺失或默认管理员初始化失败时返回错误。
-pub async fn initialize(
-    mut config: AdminConfig,
-    store: AdminStorePorts,
-    providers: Vec<Arc<dyn ProviderAdmin>>,
-    snapshot: Arc<dyn SnapshotControl>,
-    probes: (Arc<dyn AccountProbe>, Arc<dyn ports::proxy::ProxyProbe>),
-    client_distribution: Arc<dyn ClientDistributionResolver>,
-    system: Arc<dyn SystemOperations>,
-) -> Result<AdminBundle, AdminError> {
-    let (probe, proxy_probe) = probes;
-    config
-        .resolve_and_validate(Path::new("."))
-        .map_err(|error| AdminError::invalid(error.to_string()))?;
-    let registry = ProviderAdminRegistry::new(providers).map_err(map_provider_registry_error)?;
-    let openai = registry
-        .require(&provider_kind(OPENAI_PROVIDER_KIND)?)
-        .map_err(map_provider_registry_error)?;
-    let xai = registry
-        .require(&provider_kind(XAI_PROVIDER_KIND)?)
-        .map_err(map_provider_registry_error)?;
+pub use use_case::peer_link::upstream::{
+    PeerUpstreamBundle, initialize as initialize_peer_upstream,
+};
 
-    let auth = Arc::new(DefaultAuthService::new(
-        config.default_username,
-        config.session_ttl_minutes,
-        store.auth(),
-    ));
-    auth.ensure_default_admin(config.default_password.expose())
-        .await?;
-
-    let accounts = Arc::new(DefaultAccountsService::new(
-        store.accounts(),
-        store.account_runtime(),
-        registry.clone(),
-        snapshot.clone(),
-        probe.clone(),
-    ));
-    let backup_ports = store.backup();
-    let backups = Arc::new(DefaultBackupService::new(
-        backup_ports.repository(),
-        backup_ports.object_store(),
-        store.auth(),
-        snapshot.clone(),
-    ));
-    let backup_task = backup::task::BackupTask::new(
-        backup_ports.repository(),
-        backup_ports.dump(),
-        backup_ports.object_store(),
-    );
-    let services = AdminServices {
-        proxies: Arc::new(use_case::proxies::DefaultProxiesService::new(
-            store.proxies(),
-            proxy_probe,
-            snapshot.clone(),
-            registry.clone(),
-        )),
-        auth,
-        accounts,
-        account_groups: Arc::new(DefaultAccountGroupService::new(
-            store.account_groups(),
-            store.account_runtime(),
-            snapshot.clone(),
-        )),
-        client_keys: Arc::new(DefaultClientKeyService::new(
-            store.client_keys(),
-            snapshot.clone(),
-        )),
-        client_distribution: Arc::new(DefaultClientDistributionService::new(client_distribution)),
-        observability: Arc::new(DefaultObservabilityService::new(
-            store.observability(),
-            store.accounts(),
-            store.settings(),
-            registry,
-        )),
-        settings: Arc::new(DefaultSettingsService::new(
-            store.settings(),
-            snapshot.clone(),
-        )),
-        system: Arc::new(DefaultSystemService::new(system)),
-        openai: Arc::new(DefaultOpenAiService::new(
-            openai,
-            store.accounts(),
-            store.proxies(),
-            snapshot.clone(),
-        )),
-        xai: Arc::new(DefaultXaiService::new(
-            xai,
-            store.accounts(),
-            store.proxies(),
-            snapshot.clone(),
-        )),
-        backups,
-    };
-    let worker_contributions = backup_worker_contribution(backup_task)?;
-    Ok(AdminBundle {
-        services,
-        worker_contributions,
-    })
-}
-
-/// Backup Worker 注册：单个可取消 Daemon，owner 固定为 `backup`。
-fn backup_worker_contribution(
-    task: backup::task::BackupTask,
-) -> Result<Vec<WorkerContribution>, AdminError> {
-    let id = WorkerId::try_new(WorkerKind::Backup, BACKUP_WORKER_OWNER)
-        .map_err(|_| AdminError::internal("备份 Worker ID 不合法"))?;
-    let restart = DaemonRestartPolicy::try_new(Duration::from_secs(1), Duration::from_secs(60))
-        .map_err(|_| AdminError::internal("备份 Worker 重启策略不合法"))?;
-    let registration = WorkerRegistration::try_new(
-        id,
-        WorkerRunnable::Daemon {
-            restart,
-            task: Box::new(task),
-        },
-    )
-    .map_err(|_| AdminError::internal("备份 Worker 注册信息不合法"))?;
-    Ok(vec![WorkerContribution::Registration(registration)])
-}
-
-fn provider_kind(value: &'static str) -> Result<ProviderKind, AdminError> {
-    ProviderKind::new(value).map_err(|_| AdminError::internal("内置 Provider 类型不合法"))
-}
-
-fn map_provider_registry_error(error: ProviderAdminError) -> AdminError {
-    let kind = match error.kind() {
-        ProviderAdminErrorKind::Invalid | ProviderAdminErrorKind::Unsupported => {
-            AdminErrorKind::Invalid
-        }
-        ProviderAdminErrorKind::NotFound => AdminErrorKind::NotFound,
-        ProviderAdminErrorKind::Conflict => AdminErrorKind::Conflict,
-        ProviderAdminErrorKind::Ambiguous => AdminErrorKind::UpstreamResultUnknown,
-        ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
-            AdminErrorKind::Unavailable
-        }
-        ProviderAdminErrorKind::BadGateway => AdminErrorKind::BadGateway,
-        ProviderAdminErrorKind::Internal => AdminErrorKind::Internal,
-    };
-    AdminError::new(kind, "Provider 注册表初始化失败")
+/// 组合根提供给控制面的运行能力；与配置和存储端口分别传入
+pub struct AdminRuntimePorts {
+    pub upstream_info: Option<Arc<dyn ports::peer::PeerUpstreamService>>,
+    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,
+    pub plugin_distribution: Arc<dyn ports::plugins::PluginDistribution>,
+    pub plugin_inspector: Arc<dyn ports::plugins::PluginPackageInspector>,
+    pub pricing_source: Arc<dyn ports::pricing::PricingSource>,
+    pub providers: ProviderAdminRegistry,
+    pub snapshot: Arc<dyn SnapshotControl>,
+    pub account_probe: Arc<dyn AccountProbe>,
+    pub proxy_probe: Arc<dyn ports::proxy::ProxyProbe>,
+    pub client_distribution: Arc<dyn ClientDistributionResolver>,
+    pub system: Arc<dyn SystemOperations>,
+    pub client_key_verifier: Arc<dyn ClientKeyVerifier>,
 }

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

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

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

@@ -1,4 +1,4 @@
-//! 多 Provider 账号目录与连接测试的公共事实。
+//! 多 Provider 账号目录与连接测试的公共事实
 
 use std::{collections::BTreeMap, pin::Pin};
 
@@ -18,16 +18,31 @@ pub use gateway_core::account::{
     QuotaState, resolve_account_status,
 };
 
-/// 导入时统一应用的账号调度与分组设置；缺省时保留原有导入语义。
+/// 账号可用的管理操作
+#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
+pub struct ProviderAccountCapabilities {
+    pub quota: bool,
+    pub quota_refresh: bool,
+    pub profile: bool,
+    pub subscription: bool,
+    pub avatar: bool,
+    pub reset_credits: bool,
+    pub consume_reset_credit: bool,
+}
+
+/// 导入时应用的账号设置；名称只覆盖单账号导入，其余设置统一应用
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountImportSettings {
+    pub name: Option<String>,
+    pub notes: Option<String>,
     pub enabled: bool,
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
 }
 
-/// 账号列表排序字段。
+/// 账号列表排序字段
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AccountSortField {
     Email,
@@ -38,21 +53,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,
@@ -64,28 +79,42 @@ pub struct AccountListQuery {
     pub sort: Option<AccountSort>,
 }
 
-/// Admin query service 从运行态存储取得的当前账号冷却快照。
+/// Admin query service 从运行态存储取得的当前账号冷却快照
 #[derive(Debug, Clone, Default, PartialEq, Eq)]
 pub struct AccountRuntimeSnapshot {
-    pub rate_limited_until: BTreeMap<String, DateTime<Utc>>,
-    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零。
+    pub protection_rules: BTreeMap<String, Vec<gateway_core::account::AccountProtectionMatch>>,
+    pub cooldown: BTreeMap<String, gateway_core::account::AccountCooldown>,
+    /// `None` 表示实时 lease 存储不可用；`Some` 中未出现的账号当前使用量为零
     pub in_flight: Option<BTreeMap<String, u64>>,
 }
 
-/// Optional account membership filter.
+/// 恢复任务读取的冻结快照；generation 将异步结果绑定到本次冻结
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountFreeze {
+    pub credential_revision: Revision,
+    pub until: DateTime<Utc>,
+    pub generation: String,
+    pub requires_probe: bool,
+    pub duration_seconds: Option<u64>,
+    pub probe_model: Option<String>,
+    pub protection_rules: Vec<gateway_core::account::AccountProtectionMatch>,
+}
+
+/// 可选的账号分组成员筛选条件
 #[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,
     pub provider_kind: ProviderKind,
     pub groups: Vec<AccountGroupRef>,
     pub name: String,
+    pub notes: Option<String>,
     pub email: Option<String>,
     pub upstream_user_id: Option<String>,
     pub upstream_account_id: Option<String>,
@@ -98,7 +127,10 @@ pub struct AccountRecord {
     pub enabled: bool,
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
+    pub model_access: gateway_core::account::AccountModelAccess,
+    pub outbound_proxy_id: Option<String>,
     pub outbound_proxy: Option<gateway_core::account::OutboundProxy>,
+    pub outbound_proxy_enabled: bool,
     pub credential_state: CredentialState,
     pub credential_observed_at: DateTime<Utc>,
     pub quota: QuotaState,
@@ -108,42 +140,22 @@ pub struct AccountRecord {
     pub updated_at: DateTime<Utc>,
 }
 
-/// 单一货币的账号成本聚合。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountCost {
-    pub currency: String,
-    pub amount: super::observability::DecimalAmount,
+impl AccountRecord {
+    /// 配置保留绑定，执行请求时禁用代理按直连处理
+    #[must_use]
+    pub fn effective_outbound_proxy(&self) -> Option<&gateway_core::account::OutboundProxy> {
+        self.outbound_proxy
+            .as_ref()
+            .filter(|_| self.outbound_proxy_enabled)
+    }
 }
 
-/// 账号在一个模型上的历史用量。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountModelUsage {
-    pub model: String,
-    pub request_count: u64,
-    pub success_count: u64,
-    pub input_tokens: Option<u64>,
-    pub output_tokens: Option<u64>,
-    pub cached_tokens: Option<u64>,
-    pub cache_write_tokens: Option<u64>,
-    pub reasoning_tokens: Option<u64>,
-    pub image_input_tokens: Option<u64>,
-    pub image_output_tokens: Option<u64>,
-    pub image_request_count: u64,
-    pub image_request_failed_count: u64,
-    pub total_tokens: Option<u64>,
-    pub cost_coverage: super::observability::CostCoverage,
-    pub costs: Vec<AccountCost>,
-    pub last_used_at: DateTime<Utc>,
-}
+pub use super::observability::{
+    AccountModelUsage, AccountPoolMetrics as AccountSummary, AccountRequestBucket,
+    CurrencyCost as AccountCost,
+};
 
-/// 账号在一个小时窗口内的请求数。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AccountRequestBucket {
-    pub bucket_start: DateTime<Utc>,
-    pub request_count: u64,
-}
-
-/// 账号历史用量聚合。
+/// 账号历史用量聚合
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsage {
     pub account_id: String,
@@ -151,9 +163,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,
@@ -166,9 +178,9 @@ pub struct AccountUsage {
     pub models: Vec<AccountModelUsage>,
 }
 
-/// 某个账号在调用方指定时间窗口内的本地用量查询。
+/// 某个账号在调用方指定时间窗口内的本地用量查询
 ///
-/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义。
+/// `key` 只用于把聚合结果关联回调用方的窗口，不承载 Provider 私有语义
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowQuery {
     pub account_id: String,
@@ -176,7 +188,7 @@ pub struct AccountUsageWindowQuery {
     pub range: TimeRange,
 }
 
-/// 一个账号时间窗口用量查询的结果。
+/// 一个账号时间窗口用量查询的结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUsageWindowResult {
     pub account_id: String,
@@ -184,7 +196,7 @@ pub struct AccountUsageWindowResult {
     pub usage: AccountUsage,
 }
 
-/// 账号列表页所需的完整存储事实。
+/// 账号列表页所需的完整存储事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPage {
     pub config_revision: Revision,
@@ -193,69 +205,73 @@ pub struct AccountPage {
     pub summary: AccountSummary,
 }
 
-/// 同一状态快照下的账号事实与唯一状态投影。
+/// 同一状态快照下的账号事实与唯一状态投影
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountPageItem {
+    pub protection_rules: Vec<gateway_core::account::AccountProtectionMatch>,
     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 name: Option<String>,
+    /// 缺省保留备注；空字符串清空备注
+    pub notes: Option<String>,
     pub enabled: bool,
     pub concurrency_limit: Option<AccountConcurrencyLimit>,
     pub weight: AccountWeight,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
     pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
-/// 账号更新结果。
+/// 账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountUpdateResult {
     pub config_revision: Revision,
     pub account_id: gateway_core::account::ProviderAccountId,
 }
 
-/// 一批账号可编辑事实的一次性替换命令。
+/// 仅修改显式字段的批量账号设置命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct BatchUpdateAccounts {
     pub account_ids: Vec<String>,
-    pub enabled: bool,
-    pub concurrency_limit: Option<AccountConcurrencyLimit>,
-    pub weight: AccountWeight,
-    pub group_ids: Vec<gateway_core::routing::AccountGroupId>,
+    pub enabled: Option<bool>,
+    pub concurrency_limit: Option<Option<AccountConcurrencyLimit>>,
+    pub weight: Option<AccountWeight>,
+    pub model_access: Option<gateway_core::account::AccountModelAccess>,
+    pub group_ids: Option<Vec<gateway_core::routing::AccountGroupId>>,
     pub outbound_proxy: Option<super::proxies::AccountProxySelection>,
 }
 
-/// 批量账号更新结果。
+/// 批量账号更新结果
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AccountsUpdateResult {
     pub config_revision: Revision,
     pub account_ids: Vec<gateway_core::account::ProviderAccountId>,
 }
 
-/// 账号批量删除命令。
+/// 账号批量删除命令
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DeleteAccounts {
     pub account_ids: Vec<String>,
 }
 
-/// 账号连接测试的语义事件。
+/// 账号连接测试的语义事件
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum AccountConnectionTestEvent {
     Started {
@@ -284,6 +300,27 @@ pub enum AccountConnectionTestEvent {
     },
 }
 
-/// 每次连接测试独占的有限事件流。
+/// 每次连接测试独占的有限事件流
 pub type AccountConnectionTestEventStream =
     Pin<Box<dyn Stream<Item = AccountConnectionTestEvent> + Send + 'static>>;
+
+/// 单个账号普通并发池的实时租约明细，不关联请求历史
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountConcurrencyEntry {
+    pub lease_id: String,
+    pub request_id: Option<String>,
+    pub client_key_id: Option<String>,
+    pub client_key_name: Option<String>,
+    pub model: Option<String>,
+    pub client_ip: Option<String>,
+    pub started_at: Option<DateTime<Utc>>,
+    pub acquired_at: Option<DateTime<Utc>>,
+}
+
+/// 同一次 Redis 读取中的当前占用数和分页明细
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AccountConcurrencyPage {
+    pub entries: Vec<AccountConcurrencyEntry>,
+    pub total: u64,
+    pub observed_at: DateTime<Utc>,
+}

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

@@ -0,0 +1,68 @@
+//! 统计投影的新鲜度、覆盖范围与预计算费用合同
+
+use chrono::{DateTime, Utc};
+
+use super::observability::{
+    DecimalAmount, RequestMetricPoint, UsageConcurrencyPoint, 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)]
+pub struct UsageInsightsObservation {
+    pub overview: UsageOverview,
+    pub trend: Vec<RequestMetricPoint>,
+    pub costs: Vec<UsageProjectedCostPoint>,
+    pub concurrency: Vec<UsageConcurrencyPoint>,
+}

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

@@ -0,0 +1,159 @@
+//! 管理写入的审计分类；适配器只能补充事务实际写入的字段与实体标识
+
+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,
+    BackupCreate,
+    BackupDelete,
+    BackupConnectionTest,
+    BackupDownloadUrl,
+    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::BackupCreate => ("backup.created", "backup"),
+            Self::BackupDelete => ("backup.delete_requested", "backup"),
+            Self::BackupConnectionTest => ("backup.s3_connection_tested", "backup_settings"),
+            Self::BackupDownloadUrl => ("backup.download_url_created", "backup"),
+            Self::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(),
+        }
+    }
+}

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

@@ -1,23 +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,
@@ -32,6 +39,7 @@ impl AdminRequestContext {
                 admin_user_id: admin_user_id.clone(),
             },
             AdminPrincipal::ApiKey => MutationActor::AdminApiKey,
+            AdminPrincipal::Plugin { .. } => MutationActor::System,
         };
         MutationContext {
             actor,
@@ -40,47 +48,139 @@ impl AdminRequestContext {
     }
 }
 
-/// 管理员登录命令。
+/// 登录方式只决定凭据验证流程，不能直接授予会话权限
 #[derive(Clone, PartialEq, Eq)]
-pub struct LoginCommand {
-    pub username: Option<String>,
-    pub password: String,
+pub enum LoginCommand {
+    Admin {
+        username: Option<String>,
+        password: String,
+    },
+    Key {
+        api_key: String,
+    },
 }
 
 impl std::fmt::Debug for LoginCommand {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            Self::Admin { username, .. } => formatter
+                .debug_struct("AdminLogin")
+                .field("username", username)
+                .field("password", &"[REDACTED]")
+                .finish(),
+            Self::Key { .. } => formatter
+                .debug_struct("KeyLogin")
+                .field("api_key", &"[REDACTED]")
+                .finish(),
+        }
+    }
+}
+
+/// 登录或刷新后仅向当前浏览器交付的会话凭据
+#[derive(Clone, PartialEq, Eq)]
+pub struct SessionGrant {
+    pub session_id: String,
+    pub refresh_token: Option<String>,
+    pub session: AuthSession,
+}
+
+impl std::fmt::Debug for SessionGrant {
     fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         formatter
-            .debug_struct("LoginCommand")
-            .field("username", &self.username)
-            .field("password", &"[REDACTED]")
+            .debug_struct("SessionGrant")
+            .field("session_id", &"[REDACTED]")
+            .field(
+                "refresh_token",
+                &self.refresh_token.as_ref().map(|_| "[REDACTED]"),
+            )
+            .field("session", &self.session)
             .finish()
     }
 }
 
-/// 登录成功后返回的会话事实。
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct LoginResult {
-    pub session_id: String,
-    pub expires_at: DateTime<Utc>,
-}
-
-/// 登录状态机可被 API 精确映射的失败类型。
+/// 登录状态机可被 API 精确映射的失败类型
 #[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
 pub enum LoginError {
-    #[error("invalid administrator credentials")]
+    #[error("invalid login credentials")]
     InvalidCredentials,
-    #[error("administrator authentication is unavailable")]
+    #[error("too many login attempts")]
+    TooManyAttempts { retry_after_seconds: u64 },
+    #[error("authentication is unavailable")]
     Unavailable,
 }
 
-/// Redis 中可恢复的管理员会话。
+impl From<ClientAuthenticationError> for LoginError {
+    fn from(error: ClientAuthenticationError) -> Self {
+        match error {
+            ClientAuthenticationError::InvalidKey => Self::InvalidCredentials,
+            ClientAuthenticationError::SnapshotUnavailable
+            | ClientAuthenticationError::ProviderUnavailable => Self::Unavailable,
+        }
+    }
+}
+
+/// 服务端已验证的身份绑定，不保存密码或原始 API Key
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AdminSession {
-    pub admin_user_id: String,
+pub enum SessionSubject {
+    Admin {
+        admin_user_id: String,
+        credential_fingerprint: String,
+    },
+    Key {
+        client_key_id: ClientApiKeyId,
+    },
+}
+
+/// 仅已登录管理员可以修改自己的密码
+pub struct ChangePassword {
+    pub current_password: String,
+    pub new_password: String,
+}
+
+impl std::fmt::Debug for ChangePassword {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.write_str("ChangePassword([REDACTED])")
+    }
+}
+
+/// 访问有效期与逻辑会话；没有续期凭据的会话保持固定期限
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct AuthSession {
+    pub subject: SessionSubject,
+    pub expires_at: DateTime<Utc>,
+    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,
@@ -89,7 +189,7 @@ pub enum AuditActorKind {
     Anonymous,
 }
 
-/// 管理写操作留下的最小审计事实。
+/// 管理写操作留下的最小审计事实
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct AdminAuditEvent {
     pub id: String,

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

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

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

@@ -1,8 +1,10 @@
-//! S3 备份领域模型、状态机与稳定错误。
+//! S3 备份领域模型、状态机与稳定错误
 //!
-//! 领域类型只携带事实，不承载基础设施细节。Secret 使用 [`secrecy::SecretString`]，
-//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志。管理员身份等审计事实
-//! 只存在于 `admin_audit_events`，本模型不重复保存。
+//! 领域类型只携带事实，不承载基础设施细节
+//! Secret 使用 [`secrecy::SecretString`]，
+//! 全流程不实现 `Serialize`，避免被错误地写入 wire 或日志
+//! 管理员身份等审计事实
+//! 只存在于 `admin_audit_events`，本模型不重复保存
 
 use std::fmt;
 
@@ -12,7 +14,7 @@ use uuid::Uuid;
 
 use super::PageSize;
 
-/// 备份触发来源。
+/// 备份触发来源
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum BackupTriggerKind {
     Manual,
@@ -20,7 +22,7 @@ pub enum BackupTriggerKind {
 }
 
 impl BackupTriggerKind {
-    /// 稳定持久化值。
+    /// 稳定持久化值
     #[must_use]
     pub const fn as_str(self) -> &'static str {
         match self {
@@ -29,7 +31,7 @@ impl BackupTriggerKind {
         }
     }
 
-    /// 解析持久化值。
+    /// 解析持久化值
     #[must_use]
     pub fn parse(value: &str) -> Option<Self> {
         match value {
@@ -46,11 +48,11 @@ impl fmt::Display for BackupTriggerKind {
     }
 }
 
-/// 备份任务状态机（六状态）。
+/// 备份任务状态机（六状态）
 ///
 /// 迁移 `backup_records_lifecycle_ck` 与字段空值语义共同定义合法持久化行；
-/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足。
-/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态。
+/// [`Self::allows_transition_to`] 只约束领域内的显式状态迁移，两层都必须满足
+/// 删除成功后记录行被硬删除，因此不存在 `deleted` 终态
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum BackupStatus {
     Queued,
@@ -62,7 +64,7 @@ pub enum BackupStatus {
 }
 
 impl BackupStatus {
-    /// 稳定持久化值。
+    /// 稳定持久化值
     #[must_use]
     pub const fn as_str(self) -> &'static str {
         match self {
@@ -75,7 +77,7 @@ impl BackupStatus {
         }
     }
 
-    /// 解析持久化值。
+    /// 解析持久化值
     #[must_use]
     pub fn parse(value: &str) -> Option<Self> {
         match value {
@@ -89,19 +91,19 @@ impl BackupStatus {
         }
     }
 
-    /// 该状态是否消耗全局活跃名额。
+    /// 该状态是否消耗全局活跃名额
     #[must_use]
     pub const fn is_active(self) -> bool {
         matches!(self, Self::Queued | Self::Dumping | Self::Uploading)
     }
 
-    /// 该状态是否允许进入删除流程。
+    /// 该状态是否允许进入删除流程
     #[must_use]
     pub const fn can_be_deleted(self) -> bool {
         matches!(self, Self::Completed | Self::Failed)
     }
 
-    /// 领域内允许的显式迁移。
+    /// 领域内允许的显式迁移
     #[must_use]
     pub fn allows_transition_to(self, target: BackupStatus) -> bool {
         matches!(
@@ -124,7 +126,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}.sql.gz`
 ///
 /// 规范化规则：prefix 不得为空、不得以前导 `/` 开头、不得包含 `..`、反斜杠或控制字符；
-/// 输出统一使用 `/` 分隔且不含空段。
+/// 输出统一使用 `/` 分隔且不含空段
 pub fn build_object_key(
     prefix: &str,
     backup_id: &str,
@@ -460,7 +510,7 @@ pub fn build_object_key(
 ) -> Result<String, BackupError> {
     let prefix = normalize_prefix(prefix)?;
     Ok(format!(
-        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.dump",
+        "{prefix}/{}/{:02}/{:02}/codex-proxy-rs_{}_{}.sql.gz",
         at.format("%Y"),
         at.format("%m"),
         at.format("%d"),
@@ -469,22 +519,22 @@ pub fn build_object_key(
     ))
 }
 
-/// 下载文件名：`codex-proxy-rs_{短 id}.dump`，与对象 key 的文件名一致。
+/// 下载文件名：`codex-proxy-rs_{短 id}.sql.gz`，与对象 key 的文件名一致
 #[must_use]
 pub fn build_download_file_name(backup_id: &str) -> String {
-    format!("codex-proxy-rs_{}.dump", short_backup_id(backup_id))
+    format!("codex-proxy-rs_{}.sql.gz", short_backup_id(backup_id))
 }
 
-/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex。
+/// 截取备份 id 的可读短标识：去掉 `backup_` 前缀，最多保留 8 位 hex
 #[must_use]
 fn short_backup_id(backup_id: &str) -> String {
     let hex = backup_id.strip_prefix("backup_").unwrap_or(backup_id);
     hex.get(..8).unwrap_or(hex).to_owned()
 }
 
-/// 规范化并校验对象 prefix。
+/// 规范化并校验对象 prefix
 ///
-/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝。
+/// 返回去掉尾部 `/` 的规范 prefix；空串、前导 `/`、`..` 段、反斜杠和控制字符均拒绝
 pub fn normalize_prefix(prefix: &str) -> Result<String, BackupError> {
     if prefix.is_empty() || prefix.starts_with('/') {
         return Err(BackupError::new(
@@ -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>>,

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

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