mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-06 08:06:19 +00:00
docs: prioritize official Codex behavior and clarify comments
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Zyy
Codex
@@ -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#项目约定)的对应条目
|
||||
|
||||
@@ -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 缺陷，也不把第三方补偿方案当成预期行为；症状反馈仍不以证明根因为前提
|
||||
|
||||
## 正文与证据
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -7,10 +7,12 @@
|
||||
2. 先核实 PR 要解决的问题是否成立：提取触发场景、预期行为和声称的原因，在目标分支基线检查实际行为。
|
||||
按入口的公共核对收集一手证据，区分原有问题、环境或配置差异与 PR 新引入的问题，说明主分支已覆盖的部分。
|
||||
3. 从官方方案评估解决方向：说明官方如何处理同一场景，检查 PR 是否遵循其协议语义和职责归属、
|
||||
是否复用已有能力或正确传递官方合同；核对偏离官方方案的理由与运行证据。
|
||||
是否复用已有能力或正确传递官方合同；按入口的官方行为优先约束核对偏离的必要性、最小范围、行为代价与运行证据。
|
||||
审查 OpenAI 官方上游与 Codex 的对接时，默认官方返回与 Codex 兼容、直接对接正常，重点检查本项目是否误解、
|
||||
改写或破坏官方合同。不得仅凭自行构造的异常上游数据揣测官方不兼容，也不据此报告缺陷、提出改进建议，
|
||||
或要求增加防御分支与测试。讨论特定版本或场景的对接例外须有真实响应或实际复现证据，并区分代理链路与官方直连。
|
||||
真实复现上游错误或补偿后成功，也不能单独证明 CPR 应改写请求；缺少必要性依据的行为偏离须在解决方向中明确指出，
|
||||
不因测试通过而给出方案合理的结论。网关资源策略单独核对容量依据与客户端影响，不以官方客户端没有同类池策略就判错。
|
||||
4. 按贡献文档的审查维度追踪完整调用链，找到共享业务事实、同类实现及已有验证。
|
||||
对既有特殊分支查清服务的场景，再判断本次改动是否引入或加重问题。
|
||||
主动检查本次变更新引入或加重的冗余与代码异味，说明具体位置、维护成本或行为影响及最小修复方向；
|
||||
|
||||
@@ -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 为准
|
||||
|
||||
## 按当前步骤读取
|
||||
|
||||
|
||||
@@ -31,6 +31,7 @@ description: Codex Proxy RS 的版本规划、发布说明、正式或预发行
|
||||
|
||||
## 必须保持的边界
|
||||
|
||||
- 发行范围涉及 Codex 兼容性变化时，按[官方行为优先约束](../cpr-dev-guide/SKILL.md#参考仓库的优先级)核对已有方案依据和实际验证范围；缺少依据如实列为发行风险，不以 CI 通过代替，不把网关自定义策略写成官方要求
|
||||
- `release/publish` 会提交、打 tag、推送并触发工作流，没有只读预演模式，不能用于探测或演练
|
||||
- 同名版本、超时或中断先查本地与远端状态，不删已发布 tag、不移动 tag、不强推掩盖冲突
|
||||
- 预发行不得覆盖 GitHub Latest 或镜像 `latest`，完成后回读核对
|
||||
|
||||
@@ -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<ApiKeyCredentialData, CodexCred
|
||||
if crate::transport::parse_upstream_base_url(&base_url).is_none() {
|
||||
return Err(CodexCredentialAdminError::InvalidInput);
|
||||
}
|
||||
// sub2api 接受服务根、版本前缀或完整 Responses 端点；仅在导入边界归一化
|
||||
// 外部账号的 base_url 可含服务根、版本前缀或完整 Responses 端点，仅在导入边界归一化
|
||||
base_url = base_url.trim_end_matches('/').to_owned();
|
||||
if let Some(prefix) = base_url.strip_suffix("/responses") {
|
||||
base_url = prefix.to_owned();
|
||||
|
||||
@@ -234,7 +234,7 @@ export function usageLatencyDetails(record: UsageLatencyRecord) {
|
||||
function latencySeverity(ms: number | null, thresholds: readonly [number, number, number]): 'good' | 'warn' | 'slow' | 'critical' | null {
|
||||
if (ms === null)
|
||||
return null
|
||||
// 沿用 sub2api 的固定分档，边界值进入下一档，不改变请求状态
|
||||
// 耗时按固定阈值分档，边界值进入下一档，不改变请求状态
|
||||
if (ms >= thresholds[2])
|
||||
return 'critical'
|
||||
if (ms >= thresholds[1])
|
||||
|
||||
@@ -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'],
|
||||
|
||||
Reference in New Issue
Block a user