跳转到内容
ProxAI

该改哪里

该改哪里

Section titled “该改哪里”

这页是维护者用的路由图：把常见变更请求指向源码 owner、验证路径和需要随代码一起更新的文档。

变更路由图

Section titled “变更路由图”
运行时配置项

从 `src/config.rs` 开始；更新 `config.example.toml`、`src/main.rs` 或 `src/lib.rs` 的 wiring、用户文档、参考文档和配置加载测试。

入站协议解析

从 `src/ingress/` 和 `src/protocol/` 开始；保持基于 path 的 request protocol detection，并在 routing 前 normalize。

Route matching

从 `src/routing/` 开始；保持严格 `request_protocol` guard，不要让显式 guard mismatch 静默 fallthrough。

Provider request 行为

从 `src/provider/*/request` 开始；model rewrite、projection 和 serialization 属于 provider 侧。

Provider transport

从 `src/provider/*/transport` 开始；auth headers、上游 URL 构造和 HTTP send 不应进入纯 translation。

协议转换

从 `src/translation/` 开始；保持 request/response/stream conversion 在 carrier 边界上是纯协议转换。

流式语义

从 SSE scanner、streaming translation modules 和 provider response observers 开始；保持终止事件、Unicode 安全和工具调用卡住处理。

客户端错误

从 `src/error/` 开始；保持稳定、紧凑、安全的错误投影和安全上游 header 保留。

Capture/logging

从 `src/observe/` 开始；日志保持紧凑、结构化、body-safe，并与 reference phase 名称一致。

任务检查表

Section titled “任务检查表”
  1. 1

    新增或修改运行时配置字段

    目标: 让运行时配置继续以 config.toml 和被跟踪示例为中心。

    操作
    • 更新 src/config.rs。
    • 在 config.example.toml 加简洁示例/注释。
    • 只在需要时接入启动或运行时状态。
    • 更新 using/configuration 和 reference/configuration。
    • 新增或调整配置加载/default 测试。

    验证: just site check 和相关 Rust 配置测试与新默认值、文档一致。

    配置流程配置参考
  2. 2

    新增协议转换路径

    目标: 保持显式 pair-oriented translation。

    操作
    • 只有 inbound → provider request 行为受支持时才加 request conversion。
    • Provider → inbound response 行为受支持时才加非流式 response conversion。
    • 流式转换单独实现；不要假设非流式支持就等于流式支持。
    • 更新兼容性文档和行为测试。

    验证: 不支持的 pair 显式失败；支持的 pair 有 payload 和 stream terminal semantics 覆盖。

    协议转换兼容性矩阵
  3. 3

    修复流式回归

    目标: 保持 bytes、事件顺序、终止检测和语义 timeout。

    操作
    • 用最小 stream fixture 复现。
    • 判断失败位于 carrier、SSE event semantics、protocol conversion 还是客户端响应重建。
    • 按需增加终止事件、不完整工具流、工具参数卡住或 Unicode chunk 边界覆盖。

    验证: 先跑目标 streaming tests，再扩大到 e2e 验证。

    流式内部机制流式行为
  4. 4

    修改错误渲染

    目标: 保持错误紧凑、稳定、安全、有诊断价值。

    操作
    • 把内部错误映射到稳定客户端类型。
    • 保留 Retry-After 等安全上游 header。
    • 避免泄露私有 bodies、auth headers、API keys 或 prompts。
    • 更新 reference error types 和行为契约。

    验证: 当 stream state 相关时，HTTP 与 SSE 错误行为都要覆盖。

    错误流程错误响应

源码归属表

Section titled “源码归属表”
如果你要改主要源码区域还要检查
CLI flagssrc/cli/README.md, README_CN.md, reference/cli
生成的 app-directory defaultssrc/paths.rs、配置加载代码config.example.toml、配置测试
Route protocol guardssrc/routing/reference/route-matching、proxy e2e route tests
Provider model rewritesrc/provider/*/requestProvider 设置文档和兼容性矩阵
Anthropic wire structssrc/protocol/anthropic/SDK alignment 文档和转换测试
OpenAI Responses wire 行为src/protocol/openai/responses/Responses 协议文档和转换测试
Capture phase 名称src/observe/ 和 flow localsreference/capture-phases、docs checker phase coverage
Docs IA 或双语页面site/src/content/docs/tools/check_docs_i18n.py、developer/docs-maintenance

验证顺序

Section titled “验证顺序”

优先运行覆盖变更边界的最小验证，再向外扩大。纯文档工作运行 just site check。运行时行为按 AGENTS.md 和相关测试 recipe 验证。