模块边界

本页是维护者判断代码归属的地图。拿不准时，保持协议转换显式，并避免把 provider-specific 行为混入通用 translation。

归属地图

src/pipeline/inbound.rs

从 HTTP path 检测入站协议，解析 JSON bytes，并在 core preparation 前映射 carrier 错误。

crates/proxai-core/src/ingress/

在 routing 和 translation 前归一化并校验结构化入站 payload。

crates/proxai-core/src/pipeline/

组合 ingress、routing、translation、provider request adaptation 与 response processing 的 carrier-independent façade。

crates/proxai-core/src/observe.rs

共享 observer contract、封闭的 core observation variants 和 no-op 默认实现；不包含具体 sink。

crates/proxai-core/src/protocol/

Wire structs、enums 和协议专属 event payload。不做 provider routing 决策。

crates/proxai-core/src/routing/

编译模型规则，按 request protocol/model 选择 provider 标签，改写 upstream model，并执行严格协议 guard。

crates/proxai-core/src/translation/

协议 pair 之间与 carrier 无关的 request/response/stream 转换；合法适配通过类型化 observation 报告。

crates/proxai-core/src/provider/

与 carrier 无关的 provider request payload preparation、compatibility policy、结构化响应/错误归一化和类型化 adaptation observations。

src/provider/*/request

应用层 provider projection/summary 提取、JSON 序列化和 request carrier 组装。

src/provider/*/transport

上游 URL 构造、provider-owned auth headers、HTTP send。

src/upstream/

读取 provider status、headers、非流式 body 和流式 byte carrier。

src/http_support/

HTTP response reconstruction、content-type helpers、header filtering、byte stream carriers。

src/error/

Domain error taxonomy 和紧凑的客户端错误投影。

src/observe/

结构化日志、capture phases、hints 和隐私安全诊断。

边界判断

问题	放在
是否解析客户端请求 path 或 body bytes？	`src/pipeline/inbound.rs`
是否在不引入 HTTP carrier 的前提下组合完整结构化 request/response 路径？	`crates/proxai-core/src/pipeline/`
是否归一化或校验结构化入站 payload？	`crates/proxai-core/src/ingress/`
是否定义可复用的 core observation contract 或 event？	`crates/proxai-core/src/observe.rs`
是否定义协议 JSON wire shape？	`crates/proxai-core/src/protocol/`
是否按协议/模型选择 provider 标签？	`crates/proxai-core/src/routing/`
是否把选中的 provider 标签映射到 HTTP transport？	`src/pipeline/provider_request.rs`
是否把一种协议 payload 转成另一种协议 payload？	`crates/proxai-core/src/translation/`
是否准备结构化 provider request value、改写模型或适配 provider-local request 字段？	`crates/proxai-core/src/provider/`
是否提取日志 projection/summary 或序列化 provider request body？	`src/provider/*/request`
是否归一化结构化 provider response、stream event 或 error payload？	`crates/proxai-core/src/provider/`
是否添加 provider 认证头或构造上游 URL？	`src/provider/*/transport`
是否过滤 headers 或重建 HTTP response？	`src/http_support/`
是否渲染客户端错误？	`src/error/`
是否写日志或 capture artifacts？	`src/observe/`

Observation 与日志边界

proxai-core 定义共享 Observer contract、封闭的 Observation variants 和 no-op 默认实现。Core ingress、provider normalization 与 translation 通过该 contract 发出类型化 variants。它们不选择 tracing、诊断文件、capture 存储、metrics backend 或其他具体 sink；具体实现由下游应用组合层提供。

TranslationScope 是显式的 request-scoped、phase-scoped 依赖，禁止做成全局、thread-local 或 task-local 状态。只有 pair 入口和可能发出 adapted / dropped 的语义投影路径才传递 &TranslationScope；纯 wire 转换、不需要报告信息损失的 From / TryFrom，以及 outbound constructor 都必须保持 scope-free。致命失败通过 Result 返回，不得同时为同一失败发出 observation。这里优先采用显式 scope，而不是额外返回 projection/notice 集合：streaming observation 本来就应随事件即时发出，而共享 Observer 已允许下游在需要时把 observation 收集成数据。

对于 request-scoped 代码，稳定的生命周期和领域事件应通过 ObserveContext 发出。ObserveSinks 再决定一个 point 应进入日志、diagnostics、capture，还是同时进入多个 sink。只有 logging sink 负责把 observation 转成 tracing event，并选择日志级别和输出格式。

场景	使用方式
Core 中合法但有损的适配，或 ingress compatibility event	通过共享 `Observer` 发出类型化 `Observation` variant；具体 sink 由下游决定。
请求生命周期、协议/provider 结果或失败现场	使用带类型 point 的 `ObserveContext`。
Logging sink 实现	直接使用 `tracing`；日志级别和格式在这里决定。
Observation/capture 子系统自身失败	直接使用 `tracing`，避免 observer 递归观测自身。
没有 request context 的进程启动、配置或后台任务	直接使用 `tracing`。
临时局部实现调试	使用 `tracing::trace!`；若反复用于真实诊断，则提升为 observe point。

反模式

避免	原因
把 HTTP `Response` 传进 `crates/proxai-core/src/translation/`	Translation 应在 carrier 边界保持纯粹。
在 translation 中添加 provider auth 逻辑	Auth 是 provider transport 行为，不是协议转换。
把 provider 名称当协议值使用	Provider 名称是任意用户标签。
协议 guard mismatch 后静默 fallback	匹配 route 但 `request_protocol` 不一致是配置错误。
为了方便记录 request body	Prompt、工具参数和输出都是私有数据。

模块边界

模块边界

归属地图

边界判断

Observation 与日志边界

反模式

相关文档