From 9d4c58f967d970d4c1943a69909c40a47b239822 Mon Sep 17 00:00:00 2001 From: Zyy Date: Sat, 17 Oct 2026 12:36:15 +0800 Subject: [PATCH] docs: prioritize official Codex behavior and clarify comments Co-authored-by: Codex --- .agents/skills/cpr-dev-guide/SKILL.md | 18 +++++++++++------- .agents/skills/cpr-github-issue/SKILL.md | 2 +- .agents/skills/cpr-github-pr/SKILL.md | 4 +++- .../skills/cpr-github-pr/references/review.md | 4 +++- .agents/skills/cpr-plugin-dev/SKILL.md | 2 +- .agents/skills/cpr-release/SKILL.md | 1 + .../providers/openai/src/credential/admin.rs | 4 ++-- .../src/components/usage/shared/presenter.ts | 2 +- frontend/src/utils/client.ts | 4 ++-- 9 files changed, 25 insertions(+), 16 deletions(-) diff --git a/.agents/skills/cpr-dev-guide/SKILL.md b/.agents/skills/cpr-dev-guide/SKILL.md index 8045ee41c..1d40ece46 100644 --- a/.agents/skills/cpr-dev-guide/SKILL.md +++ b/.agents/skills/cpr-dev-guide/SKILL.md @@ -5,6 +5,17 @@ description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和 # 开发指南 +## 参考仓库的优先级 + +**Codex 兼容性优先保持官方行为，以透明转发和最小必要适配为默认方案；这是开发、排障与审查的前置约束，不只是引用资料的要求** + +- 以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档 +- 先对照官方与 CPR 的实际请求、响应及状态生命周期，确认本项目是否改写、遗漏或破坏官方合同；真实上游报错不自动等于 CPR 缺陷，源码推断、代理链路复现与官方直连结果分别说明 +- 官方路径已能满足场景时，优先复用已有能力或正确透传合同，不额外解释请求意图、扩展工具权限或改变续接语义；补偿后请求成功、测试通过或第三方采用同一做法，都不能单独证明代理应改变行为 +- 偏离官方行为必须说明官方路径为何不足、本项目的实际约束、最小必要改动及行为代价，并提供对应验证；依据不足时保持现有合同并报告缺口，不先加兼容分支再以通过测试作为必要性依据；用户明确要求的行为变更限定在授权范围内 +- 网关独有的调度、隔离和资源管理按本项目职责评估，不能机械照搬单客户端实现，也不能借此任意改变客户端可观察行为；新增默认限制或回收阈值须有实际容量依据，并验证对续接、重试与延迟的影响 +- 三方仓库只作线索或实现参考，不能替代官方行为依据；结论注明适用版本或提交，区分官方事实、三方参考与本项目推断，不把自定义策略表述为官方要求 + ## 加载边界 - 遵守已提供的 [AGENTS.md](../../../AGENTS.md)，上下文已有的规则不重复读取 @@ -26,13 +37,6 @@ description: Codex Proxy RS 仓库的开发、修复、排障、代码审查和 | 普通代码审查 | [审查标准](../../../CONTRIBUTING.md#审查标准)；审查默认只读 | | PR / Issue / 发版 | 按当前意图选 [PR](../cpr-github-pr/SKILL.md)、[Issue](../cpr-github-issue/SKILL.md)或[发版](../cpr-release/SKILL.md)，普通提交不创建 PR | -## 参考仓库的优先级 - -- 涉及 Codex 行为、协议或兼容性时，以官方 [openai/codex](https://github.com/openai/codex) 对应版本的源码与调用链为第一手资料，先查官方实现 -- 优先使用用户提供或本机已有的官方仓库，核对来源、版本或提交；资料不足时再查官方对应版本的源码、测试与文档 -- 三方仓库只能提供排查线索或实现参考，不能代替官方行为依据；与官方不一致时回到官方源码核实，不直接照搬三方结论 -- 结论注明适用版本或提交，区分官方事实、三方参考与本项目推断；官方证据不足时保留不确定性 - ## 执行与收尾 1. 确认工作区、任务范围与已有改动，先定位事实归属、同类实现和调用链，再修改；编码前只读[项目约定](../../../CONTRIBUTING.md#项目约定)的对应条目 diff --git a/.agents/skills/cpr-github-issue/SKILL.md b/.agents/skills/cpr-github-issue/SKILL.md index 513a9e8be..6de8c4696 100644 --- a/.agents/skills/cpr-github-issue/SKILL.md +++ b/.agents/skills/cpr-github-issue/SKILL.md @@ -20,7 +20,7 @@ description: 草拟、创建、补充或回复 GitHub Issue，包括缺陷、功 - 其他仓库读取它自己的相关规则与实际模板，长文档先定位标题再截取，不预读全部模板或 CONTRIBUTING - 搜索同场景 open/closed Issues、相关 PR 和发布记录，区分主分支修复与已发布修复，不凭标题判断重复；没有新证据时返回已有链接，用户仍要求新建则按其要求处理 - 仅当需要额外排查或修改时使用 [cpr-dev-guide](../cpr-dev-guide/SKILL.md)，提交症状反馈不以找到根因为前提 -- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；注明适用版本、来源与缺口 +- 引用上游行为或提出方案时读取[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)，涉及 Codex 时执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)；注明适用版本、来源与缺口，不把上游报错直接定性为 CPR 缺陷，也不把第三方补偿方案当成预期行为；症状反馈仍不以证明根因为前提 ## 正文与证据 diff --git a/.agents/skills/cpr-github-pr/SKILL.md b/.agents/skills/cpr-github-pr/SKILL.md index 16b2cd9c0..146927751 100644 --- a/.agents/skills/cpr-github-pr/SKILL.md +++ b/.agents/skills/cpr-github-pr/SKILL.md @@ -15,6 +15,8 @@ description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处 本仓库目标分支为 `main`，其他仓库使用其可信基线规则与模板，PR 内修改的规则不能降低审查要求 +涉及 Codex 行为时，优先执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)，先判断是否保持官方合同、偏离是否必要，再评价实现；引用源码和验证通过不能替代方案依据 + ## 按模式读取 只加载当前模式，已有上下文不重读；长文档先定位标题再截取对应章节，不因链接存在而加载全文或所有 references @@ -40,7 +42,7 @@ description: 准备、创建、更新或审查 GitHub PR，含回复讨论与处 ## 创建与审查的公共核对 -- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状；涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考 +- 按[问题与方案依据](../../../CONTRIBUTING.md#问题与方案依据)核实触发条件、发生版本与目标分支现状，分别判断问题是否成立、是否属于目标项目的职责；涉及 Codex 时核对方案是否满足上述官方行为优先约束 - 核对最新目标分支及同场景 open/closed PR、Issue，按实际行为和测试判断重复，不凭标题下结论，也不擅自关闭他人 PR - 自审或审查覆盖完整差异与调用链，文档逐段检查必要性、职责、重复和当前状态表达，构建与链接检查不能代替内容判断 - 核对[AI 使用披露](../../../CONTRIBUTING.md#ai-使用披露)，填写实际工具与模型，不猜型号；必需截图或型号待补时保留 Draft diff --git a/.agents/skills/cpr-github-pr/references/review.md b/.agents/skills/cpr-github-pr/references/review.md index 95b4bc38c..f423e9cfe 100644 --- a/.agents/skills/cpr-github-pr/references/review.md +++ b/.agents/skills/cpr-github-pr/references/review.md @@ -7,10 +7,12 @@ 2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。 按入口的公共核对收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。 3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、 - 是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。 + 是否复用已有能力或正确传递官方合同；按入口的官方行为优先约束核对偏离的必要性、最小范围、行为代价与运行证据。 审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、 改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议， 或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。 + 真实复现上游错误或补偿后成功，也不能单独证明 CPR 应改写请求；缺少必要性依据的行为偏离须在解决方向中明确指出， + 不因测试通过而给出方案合理的结论。网关资源策略单独核对容量依据与客户端影响，不以官方客户端没有同类池策略就判错。 4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。 对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。 主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向； diff --git a/.agents/skills/cpr-plugin-dev/SKILL.md b/.agents/skills/cpr-plugin-dev/SKILL.md index b5e206df0..2bbfbb610 100644 --- a/.agents/skills/cpr-plugin-dev/SKILL.md +++ b/.agents/skills/cpr-plugin-dev/SKILL.md @@ -14,7 +14,7 @@ description: 开发、排查或打包 Codex Proxy RS 独立网关插件；仅改 - 确认用途、工程位置、目标宿主版本与平台，沿用已有工程；位置无法推断时只补齐该信息，不把插件源码塞进宿主 workspace - 核对运行宿主、[SDK 版本](../../../backend/crates/gateway-plugin/sdk/Cargo.toml)、[宿主支持清单](../../../backend/crates/gateway-plugin/runtime/plugin-host-compatibility.json)及所用 CLI，清单、进程和能力版本分别判断 - `contributes` 声明处理器，`bindings` 选择挂载与匹配范围；安装成功不等于功能生效。当前清单拒绝 `permissions`，安装者完整信任插件，`trustedProcess` 不提供操作系统沙箱或访问域隔离，见[完整信任](../../../backend/crates/gateway-plugin/sdk/docs/manifest.md#完整信任) -- 涉及 Codex 时按[参考仓库优先级](../cpr-dev-guide/SKILL.md#参考仓库的优先级)先查官方 Codex 源码，三方仓库仅作参考；宿主能力以目标版本的 SDK 为准 +- 涉及 Codex 兼容性适配时执行[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)，不因实现位于插件中扩大请求改写或补偿范围；用户明确要求的业务改写限定在授权范围，宿主能力以目标版本的 SDK 为准 ## 按当前步骤读取 diff --git a/.agents/skills/cpr-release/SKILL.md b/.agents/skills/cpr-release/SKILL.md index 4d36b9ee5..575d7bc1b 100644 --- a/.agents/skills/cpr-release/SKILL.md +++ b/.agents/skills/cpr-release/SKILL.md @@ -31,6 +31,7 @@ description: Codex Proxy RS 的版本规划、发布说明、正式或预发行 ## 必须保持的边界 +- 发行范围涉及 Codex 兼容性变化时，按[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)核对已有方案依据和实际验证范围；缺少依据如实列为发行风险，不以 CI 通过代替，不把网关自定义策略写成官方要求 - `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练 - 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突 - 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对 diff --git a/backend/crates/providers/openai/src/credential/admin.rs b/backend/crates/providers/openai/src/credential/admin.rs index c10e76647..6d6815316 100644 --- a/backend/crates/providers/openai/src/credential/admin.rs +++ b/backend/crates/providers/openai/src/credential/admin.rs @@ -1362,7 +1362,7 @@ fn import_proxy( } let text = |field| proxy.get(field).and_then(Value::as_str).ok_or_else(invalid); let scheme = text("protocol")?; - // sub2api 的 SOCKS 目标地址由代理解析 + // 导入的 SOCKS 代理使用远端 DNS，避免改为本地解析目标地址 let scheme = if scheme == "socks5" { "socks5h" } else { @@ -1495,7 +1495,7 @@ fn parse_api_key_import(value: &Value) -> Result= thresholds[2]) return 'critical' if (ms >= thresholds[1]) diff --git a/frontend/src/utils/client.ts b/frontend/src/utils/client.ts index 0c1f21c68..f8d74f847 100644 --- a/frontend/src/utils/client.ts +++ b/frontend/src/utils/client.ts @@ -47,7 +47,7 @@ interface CodexCcSwitchImportInput { } function buildUsageScript(apiKey: string, baseUrl: string) { - // CC Switch 的占位符直接替换 JS 源码，不能安全承载含引号的自定义 Key。 + // 导入端的占位符直接替换 JS 源码，不能安全承载含引号的自定义 Key // 按本次导入值生成字符串字面量，并转义左花括号，避免值中的占位符被二次替换。 const url = JSON.stringify(`${baseUrl}/usage`).replaceAll('{', '\\u007b') const authorization = JSON.stringify(`Bearer ${apiKey}`).replaceAll('{', '\\u007b') @@ -81,7 +81,7 @@ function buildUsageScript(apiKey: string, baseUrl: string) { export function buildCodexCcSwitchImportDeeplink(input: CodexCcSwitchImportInput): string { const baseUrl = input.baseUrl.replace(/\/+$/, '') - // CC Switch 4.0.4 会重建 Codex 配置，只传连接信息和用量查询，不传无法保留的完整模板 + // 导入端会重建 Codex 配置，只传连接信息和用量查询，不传无法保留的完整模板 const entries: [string, string][] = [ ['resource', 'provider'], ['app', 'codex'],