把 TypeScript 写的 SDK 原样搬到 C# 里这事听着简单做起来全是坑。尤其对象是 Codex SDK 这种带流式响应、事件回调、多环境配置的现代 SDK不是把interface改成class、把Promise换成Task就完事的。我最近完整做了一遍这个移植前后花了两周过程中把类型映射、流式处理、错误重试这些硬骨头都啃了一遍写出来给准备动手做跨语言 SDK 移植的朋友做个参考。这篇内容适合这几类人要把 Node.js/TypeScript 生态的 SDK 移植到 .NET 服务端使用的后端工程师想在自己的 C# 桌面应用或 Unity 项目里接入 AI 编码 Agent 能力的开发者以及单纯想研究两个语言在异步、类型系统、序列化上差异的同学。我会把从项目结构设计到最终测试发布的完整链路都讲清楚代码可以直接照着抄。1. 移植动机与方案选型1.1 什么场景下需要这个 C# 版 SDK先说结论绝大多数情况下你不需要自己移植直接调 HTTP API 就行。但当你遇到下面几种场景自研移植就变得有必要了。第一种场景是团队技术栈锁定在 .NET。比如公司内部服务全是 C# 写的部署在 Windows Server 或者 Azure 上引入 Node.js 运行时只为了跑一个 SDK 很不划算。我之前遇到的一个项目就是这样网关、鉴权、消息队列全是 .NET 生态为了接 Codex 服务专门搭一套 Node 环境运维成本直接翻倍。第二种场景是离线或内网环境。很多企业开发环境不允许开发机直连外网API 请求要走内部代理网关。这种情况下用一个统一封装的 C# SDK把代理配置、证书校验、重试策略全部收敛在一个包里比让每个业务方各自拼 HTTP 请求要可控得多。第三种场景是深度集成。比如要在 WPF 桌面工具里做一个“AI 编码助手”面板或者在 Unity 编辑器里接入代码生成能力。这种桌面级应用天然是 C# 的主场用 JavaScript/TypeScript 反而要套一层 WebView别扭且难调试。我这次移植的目标很明确让业务方像调用本地方法一样调用 Codex 能力不需要理解底层 HTTP 细节同时行为和官方 TypeScript SDK 保持一致。说白了就是做一个“被 .NET 团队认可的替代品”。1.2 三种移植路线怎么选动手之前我认真对比过三条路线这里直接说结论。第一条路线是包一层 HTTP 封装只做最简单的请求转发。优点是快一天就能写完缺点是你得自己处理鉴权刷新、流式解析、错误分类、超时重试这些脏活而且每个业务方都会写一套风格迥异的调用代码。我管这叫“能用但不好用”。第二条路线是逐行翻译官方 SDK。优点是与上游行为完全对齐官方修的 bug、加的参数都能同步缺点是工程量大而且 TypeScript 里很多“灵活”的写法在 C# 里根本没有对等物比如联合类型、条件类型、泛型约束的某些高级玩法翻译过程会非常痛苦。第三条路线是参考官方 SDK 的接口设计按 C# 惯例重写实现。我最终选的就是这条。接口签名尽量对齐官方但内部实现完全按 .NET 的习惯来用HttpClient而不是fetch、用IAsyncEnumerable而不是事件流、用JsonSerializer而不是JSON.parse。这样既保证了业务方迁移成本低又不会写出“看起来像 C# 的 JavaScript”。选型时还有一个容易被忽略的点看官方 SDK 的维护活跃度。如果上游长期不更新你逐行翻译的代码会积累大量技术债如果上游很活跃你反而要花精力做版本追踪。Codex SDK 属于更新偏快的所以我特意在 C# 版里预留了接口版本号字段方便后续平滑升级。1.3 移植前必须摸清的底细拿到官方 TypeScript SDK 源码后别急着写代码先花半天把下面几件事搞清楚。首先摸清楚依赖树。TypeScript SDK 通常依赖openai这个核心包再叠加自己的封装。你得看清楚哪些依赖是必要的哪些只是顺手引的。比如有的 SDK 引了zod做参数校验C# 里就没有完全对等的库这就需要你自己决定要不要实现同样的校验强度。其次摸清楚调用链路。从用户调用某个方法开始请求怎么组装的、鉴权头怎么加的、重试逻辑在哪一层、错误怎么分类的画一张简单的调用流程图纸上的就行后面写 C# 的时候就照着这个链路走就不会漏功能。最后一定要做的是跑通官方 SDK 的端到端调用。在移植前先用 TypeScript 脚本真实调一次 Codex 接口把请求和响应的完整报文抓下来。这一步很多人会跳过但恰恰是最关键的——你后面写 C# 反序列化、流式解析全靠这份真实报文当“标准答案”。我移植过程中至少有一半的 bug 是靠对照这份报文定位的。2. 原版 SDK 的架构拆解2.1 模块划分与核心文件官方 TypeScript SDK 的源码结构并不复杂拆开看核心就这么几块客户端入口、类型定义、API 资源类、流式工具函数、错误定义。客户端入口负责配置管理和实例化比如new CodexClient({ apiKey })这种。它内部会创建一个fetch函数并绑定基础 URL、默认请求头、超时时间。C# 里对等的是CodexClient类内部持有一个配置好的HttpClient。API 资源类是最核心的部分比如client.responses.create()这样的方法就封装了对/v1/responses端点的调用。资源类通常按领域划分会话管理、消息处理、文件上传等。移植的时候最好保持同样的划分这样已有的 TypeScript 调用方在切换语言时代码结构几乎可以一一对应。类型定义就是一堆interface和type。C# 里对应的是class或record。这部分看起来机械实际最繁琐因为 TypeScript 的字段命名是snake_case而 C# 惯例是PascalCase序列化时要做命名策略映射一个字段都不能漏。流式工具函数是这块 SDK 的精华。Codex 的流式响应基于 SSEServer-Sent EventsTypeScript 端会解析data:行的 JSON 并触发各种事件。C# 端我用IAsyncEnumerableStreamEvent来等价实现调用方可以用await foreach消费体验上比事件回调清爽得多。错误定义这块也要重视起来。原版 SDK 把错误分成AuthenticationError、RateLimitError、APIConnectionError等类别C# 里我建了一套对应的异常类型确保调用方可以用catch (CodexRateLimitException)精确捕获不至于全被Exception兜住。2.2 类型系统与数据结构TypeScript 的类型系统和 C# 差别非常大移植时最容易在这里栽跟头。我整理了几个经典的映射场景。联合类型是第一个难点。比如某个字段的类型是string | nullC# 直接对应string?即可。但如果是auto | high | low这种字面量联合类型C# 没有直接对等物我建议用枚举 一个可空字符串字段来模拟或者干脆用一个带静态工厂方法的record类型把合法值约束在工厂方法里。可选字段在 TypeScript 里是field?: stringC# 里对应string? Field { get; set; }这个比较直接。但有一个细节是否需要区分“字段没传”和“字段传了 null”。前者在序列化时不输出该字段后者输出null。TypeScript 的 JSON 序列化默认会省略undefined字段C# 的System.Text.Json默认会序列化所有属性这就可能导致请求体多出空字段服务端某些严格校验会报错。解决办法是给属性加[JsonIgnore(Condition JsonIgnoreCondition.WhenWritingNull)]并且把可选值类型设计成NullableT这样没赋值就不会输出。泛型约束也是差异明显的地方。TypeScript 的T extends SomeType在 C# 里对应where T : SomeType语义上差不多但某些写法比如条件类型T extends X ? A : B在 C# 里完全没法表达只能拆成多个方法重载。移植时碰到这种高级类型玩法别硬翻译重新设计接口签名反而更清晰。2.3 流式接口与事件机制Codex SDK 最重的功能就是流式响应调用后服务端会持续推送事件比如“开始思考”“生成代码片段”“工具调用开始”“工具调用结束”“最终回答”等。TypeScript 版用EventEmitter实现调用方要注册多个事件监听器还要自己管理监听器的生命周期搞不好就会内存泄漏。C# 版我换了一种思路用IAsyncEnumerableCodexStreamEvent做统一出口。原因是await foreach天然支持取消配合CancellationToken、支持 LINQ 过滤、不会遗漏事件而且对调用方来说“按顺序消费事件流”比“注册一堆回调”更符合直觉。事件本身我用一个基类加派生子类的方式建模基类叫CodexStreamEvent只放SequenceId、EventType和原始 JSON 三个公共属性具体业务事件代码片段、工具调用请求等各自继承它。这样调用方可以先 switch 类型再处理干净利落。还有一个重要细节是结束标志。SSE 流结束有两种情况正常结束收到data: [DONE]和异常中断连接断开。TypeScript 版的处理比较隐晦C# 里我专门在流末尾抛一个CodexStreamEndedException带“完整/截断”标志让调用方明确感知到这次流式调用是不是完整结束避免把截断的结果当完整结果用。3. C# 项目搭建与类型映射3.1 项目结构与依赖项目结构我建议按功能分文件夹而不是按类型分。我这版的结构是这样Codex.Sdk/ ├── CodexClient.cs // 客户端入口 ├── Models/ // 请求/响应模型 │ ├── Requests/ │ └── Responses/ ├── Streaming/ // SSE 流式解析 │ ├── SseParser.cs │ └── CodexStreamEvent.cs ├── Exceptions/ // 异常类型 ├── Auth/ // 鉴权与 Token 刷新 ├── Http/ // HttpClient 封装与重试 └── Serialization/ // JsonSerializer 扩展依赖方面只引了System.Text.Json和Microsoft.Extensions.Http前者做序列化后者方便把HttpClient注册到 DI 容器。不需要引入第三方 JSON 库System.Text.Json在 .NET 8 上已经足够好用了。项目目标框架我定的是net8.0既支持普通服务端也能被 Unity配合 .NET Standard 兼容层和 WPF 引用。如果你要兼顾老项目可以定netstandard2.0但流式处理的实现要稍微绕一点因为IAsyncEnumerable在老框架上不可用。建议能用 .NET 8 就用 .NET 8别为了兼容拖累体验。3.2 TS 类型到 C# 的映射实战这里我放一组真实对照你们感受一下手写映射时的节奏。// TypeScript 原版 export interface CodexResponse { id: string; object: response; created_at: number; status: in_progress | completed | failed; output: ArrayResponseOutputItem; usage?: TokenUsage | null; }// C# 移植版 public sealed class CodexResponse { [JsonPropertyName(id)] public string Id { get; set; } ; [JsonPropertyName(object)] public string Object { get; set; } response; [JsonPropertyName(created_at)] public long CreatedAt { get; set; } [JsonPropertyName(status)] [JsonConverter(typeof(JsonStringEnumConverter))] public CodexResponseStatus Status { get; set; } [JsonPropertyName(output)] public ListResponseOutputItem Output { get; set; } new(); [JsonPropertyName(usage)] [JsonIgnore(Condition JsonIgnoreCondition.WhenWritingNull)] public TokenUsage? Usage { get; set; } }几个要点说一下。第一所有属性都加[JsonPropertyName]字段名严格用snake_case避免依赖全局命名策略防止某个嵌套类忘记标注导致反序列化失败。第二status这种枚举字段我用了JsonStringEnumConverter直接映射字符串。相比自己写转换器这种方式零成本只要枚举成员名和 API 返回的字符串一致就行。注意created_at我保留为long不转DateTime。原因是 API 返回的是 Unix 秒级时间戳业务方可能有不同的换算需求直接暴露长整型反而最灵活。真要转DateTimeOffset我提供了一个扩展方法ToDateTimeOffset()。第三集合属性必须初始化为空集合不要留null。这可以有效减少调用方空引用判断也算 C# 里的小习惯。再补一个容易踩的坑usage字段是联合类型TokenUsage | nullC# 映射为TokenUsage?之后JSON 反序列化在字段缺失时是null字段为null时也是null这在大多数场景没问题。但如果你需要区分“这次请求没返回 usage”和“usage 内部字段全是空的”就得单独加一个HasUsage辅助属性来标记我后续补上了这个生产环境排查问题时非常有用。3.3 JSON 序列化细节System.Text.Json默认是大小写不敏感的反序列化但序列化是严格区分大小写的。所以我的建议是所有模型类统一加[JsonPropertyName]不依赖任何全局配置。有个场景需要特别注意发送请求时某些字段不需要输出比如可选参数没设置就不该出现在 JSON 里。我前面提到了[JsonIgnore(Condition JsonIgnoreCondition.WhenWritingNull)]但还有一个更隐蔽的问题——double?和int?这类可空值类型。如果没有赋值序列化会输出null但如果服务端对“缺少字段”和“字段为 null”有不同语义就得自己控制。最简单的方式是把所有可空字段统一声明为null默认值配合WhenWritingNull忽略策略保证没赋值的字段完全不输出。另外推荐开启DefaultIgnoreCondition JsonIgnoreCondition.WhenWritingNull作为全局默认然后对个别必填但可能为空的字段单独覆盖。这样默认行为就是“空的不输出”符合 API 的常规预期。还有一个细节JsonSerializer默认不支持反序列化IAsyncEnumerableT类型不过序列化是支持的。所以流式响应不要走JsonSerializer.DeserializeAsync而是手动逐行解析 SSE再对每条data:做独立的 JSON 反序列化。这个我在下一节详细讲。4. 核心模块移植实现4.1 HTTP 客户端与鉴权C# 端 HTTP 客户端我直接用HttpClient但有几个关键配置必须做对。首先是HttpClient生命周期。不要每次请求都new HttpClient()那样会耗尽 socket 连接。正确做法是注册为单例配合IHttpClientFactory使用。我项目里是这样注册的services.AddHttpClientCodexClient((sp, client) { client.Timeout TimeSpan.FromSeconds(300); client.DefaultRequestHeaders.UserAgent.ParseAdd(codex-sdk-csharp/1.0.0); });超时时间我刻意设置得很长因为 Codex 的响应可能持续好几分钟如果调默认的 100 秒很容易误杀长任务。不过这里要注意HttpClient.Timeout是总超时包括连接和读取全程。如果你希望“连接超时 10 秒但响应可以无限等”就得用CancellationTokenSource.CancelAfter分阶段控制或者用SocketsHttpHandler的ConnectTimeout属性。鉴权这块官方 TypeScript SDK 用的是Authorization: Bearer tokenC# 里直接设置默认请求头即可。但真实业务里 token 通常会动态刷新不能写死在DefaultRequestHeaders里。我的做法是封装一个AuthHeaderHandler : DelegatingHandler每次请求前从ITokenProvider拉取最新 tokenprotected override async TaskHttpResponseMessage SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { var token await _tokenProvider.GetTokenAsync(cancellationToken); request.Headers.Authorization new AuthenticationHeaderValue(Bearer, token); return await base.SendAsync(request, cancellationToken); }注意 token 拉取之后要验证是否真的拿到了避免拿到空串发出一个无鉴权请求白白浪费一次 round trip。4.2 SSE 流式响应处理SSE 解析是这次移植里我最看重的部分也最容易写错。SSE 报文长这样data: {type:response.created,response:{...}} data: {type:response.output_item.added,output_index:0,...} data: [DONE]每个事件以data:开头事件之间用空行分隔注释行以:开头。解析思路很简单逐行读取判断是否为data:前缀如果是就把后面的内容追加到当前事件的 buffer遇到空行就认为一个事件结束把 buffer 里的 JSON 丢出去。注意data:后面的内容可能是多行的一定不能只读一行就结束。我用StreamReader.ReadLineAsync逐行读配合CancellationToken实现取消。核心解析器的简化版长这样public async IAsyncEnumerableCodexStreamEvent StreamAsync( HttpResponseMessage response, [EnumeratorCancellation] CancellationToken cancellationToken default) { await using var stream await response.Content.ReadAsStreamAsync(cancellationToken); using var reader new StreamReader(stream); var dataBuffer new StringBuilder(); while (await reader.ReadLineAsync(cancellationToken) is { } line) { if (line.StartsWith(data:, StringComparison.Ordinal)) { dataBuffer.Append(line.AsSpan(5).Trim()); } else if (line.Length 0 dataBuffer.Length 0) { var payload dataBuffer.ToString(); dataBuffer.Clear(); if (payload [DONE]) { yield break; } yield return DeserializeEvent(payload); } } }几个容易踩的坑。第一data:后面可能有前导空格我做了Trim()否则反序列化直接炸。第二[DONE]和真实 JSON 要分开处理。第三网络中断时ReadLineAsync会抛IOException我建议在外面包一层 try-catch把异常转换成CodexStreamInterruptedException并标记本次流的结束位置方便日志排查。事件反序列化我采用“先解析基础信息再按类型分发”的策略。每个 SSE 事件里都带type字段我先反序列化成一个轻量的CodexStreamEventHeader拿到type后再决定用哪个具体类型去解析。这样比每次都在一个类里硬塞几十个可空字段干净得多。4.3 异步与并发模型转换TypeScript 的Promise和 C# 的Task表面上都是异步但有些细节在移植时容易出错。第一个是取消机制。TypeScript 的AbortController对应 C# 的CancellationToken但CancellationToken是显式传递的不像 TypeScript 里可以挂在某个全局对象上。我在所有公开方法上都加了CancellationToken cancellationToken default参数调用方不传就不取消。注意default是不能被取消的 token但用它做默认值很安全符合“可选取消”的预期。第二个是并发控制。TypeScript 的fetch底层连接池由 Node 管理开发时容易忽略连接数上限。C# 里HttpClient默认对同一主机有连接数限制默认值是很大的数但老版本是 2。如果你的 Codex 服务部署在同一域名下高并发时一定要调大SocketsHttpHandler.MaxConnectionsPerServer否则会莫名其妙地卡住。第三个是死锁风险。在桌面应用里很多人会在 UI 线程上.Result或.Wait()同步等待异步方法这在写库代码时是绝对禁止的。我的代码库里所有异步方法都坚持async/await一路到底并且文档里明确标注“不要在 UI 线程同步阻塞”。曾经有同事直接.Result等流式方法结果 UI 卡死 5 分钟最后发现是同步上下文死锁。第四个是值任务优化。有些方法比如 token 刷新很轻我用ValueTask作为返回值类型减少堆分配。但对于需要跨 await 保持状态的方法还是老老实实用Task不要盲目用ValueTask折腾自己。4.4 错误处理与重试机制错误处理这块TypeScript SDK 其实做得一般我自己在 C# 版里做得更细。异常类型设计上我建了一个基类CodexException下面分CodexAuthenticationException、CodexRateLimitException、CodexApiException带Status Code和ErrorCode、CodexNetworkException。调用方只需要 catch 基类就能覆盖所有错误想精确处理单独 catch 子类也完全可以。请求失败时我先根据 HTTP 状态码分类再结合响应体里的error.code字段做二次确认。比如 401 一定是鉴权问题429 一定是限流502/503/504 属于网关类错误需要重试。这样分类比单纯看状态码更准因为有些服务会用 200 返回业务错误。重试逻辑我做成可配置策略默认规则429 和 5xx 重试最多 3 次退避策略用指数退避加抖动jitter基础间隔 1 秒每次翻倍再加 0~500ms 的随机抖动。防止多个客户端同时失败产生惊群效应。代码结构上用DelegatingHandler实现这样不管请求是从哪个方法发出重试都会自动生效。protected override async TaskHttpResponseMessage SendAsync( HttpRequestMessage request, CancellationToken cancellationToken) { var attempt 0; while (true) { try { var response await base.SendAsync(request, cancellationToken); if (ShouldRetry(response.StatusCode) attempt _maxRetries) { attempt; var delay _baseDelay * Math.Pow(2, attempt - 1) TimeSpan.FromMilliseconds(Random.Shared.Next(0, 500)); await Task.Delay(delay, cancellationToken); continue; } return response; } catch (HttpRequestException) when (attempt _maxRetries) { attempt; var delay ...; await Task.Delay(delay, cancellationToken); } } }这里有一个重要细节HttpRequestMessage默认只能发送一次重试时必须重新创建请求或设置request.Options.Set(new HttpRequestOptionsKeybool(RequestRetry), true)来允许复用。我建议在重试时直接克隆请求对象避免踩“request already sent”这个经典坑。5. 测试验证与发布5.1 对照测试方案移植完最担心的就是“和原版行为不一致”。所以我专门设计了一套对照测试同一个请求分别用 TypeScript 官方 SDK 和 C# SDK 调用然后对比两者的请求报文、响应报文和处理结果。我建了一个测试脚本用 mock 服务捕获请求。Mock 服务把 TypeScript 版发来的原始请求体存下来再把 C# 版发来的请求体存下来最后对比这两个 JSON 是否一致。这一招能快速抓到字段名、格式、默认值方面的差异。实践中我靠这个对比抓到了至少 5 个问题比如有一个可选字段我在 C# 里漏设了[JsonIgnore]导致请求体多输出了一个null字段正好被对比脚本抓个正着。响应侧我用录制的真实响应报文做回放。把一次完整的流式响应保存成文件测试时由 mock 服务逐行返回。这样测试不依赖外网也不需要真实消耗 API 额度非常适合 CI 里跑。5.2 典型结果与性能实测移植完之后我做了几组简单性能对比。单次非流式请求的耗时C# 版和 TypeScript 版差距非常小基本在 5% 以内主要波动来自网络本身。流式场景下C# 版的事件解析吞吐略高因为System.Text.Json对长字符串的解析效率还不错加上IAsyncEnumerable的按需拉取模式比事件回调更节省内存。内存方面有个值得说的点长流式响应如果一次性把整个响应体读完再解析内存峰值会很高。所以我实现流式解析时是边读边 yield理论上内存占用只跟单条事件大小有关跟整个响应长度无关。实测跑一个 10 万字符的流式回答内存占用稳定在 20MB 以内这个表现我比较满意。5.3 NuGet 打包与文档发布阶段我做了 NuGet 包版本号跟官方 SDK 做了一一映射。比如官方是v0.3.0我这边就叫0.3.0这样使用者一看版本号就知道对应关系不用查文档。打包时要特别注意.csproj里的GenerateDocumentationFile开关一定要打开生成 XML 文档。引用方会用 IntelliSense 看到每个方法和参数说明这直接影响 SDK 的“好用程度”。同时把PackageReadmeFile指向 READMENuGet 页面上就有完整使用说明。文档我写了 README 示例项目涵盖最核心的三块普通请求怎么调、流式响应怎么消费、异常怎么处理。示例代码一定自己跑过再贴我见过太多 SDK 的 README 里的代码根本编译不过这是砸招牌的事。6. 常见问题与排查技巧实录6.1 高频问题速查表这一节我直接按问题汇总都是我移植和后续维护中真实遇到过的照着排查能省很多时间。问题现象可能原因排查方法反序列化报错JSON deserialization failure字段名映射错误或snake_case没对上检查模型类的[JsonPropertyName]用抓包报文对比流式响应只拿到第一行就结束解析器过早return没有循环读行确认while循环是否把空行场景写全请求发出后一直卡住直到超时MaxConnectionsPerServer太小或超时设置不合理检查SocketsHttpHandler配置与总超时时间重试时抛“request already sent”HttpRequestMessage被重复发送重试前克隆请求对象事件流事件顺序混乱事件监听器并发消费检查是否用了多个await foreach同时消费同一个流CancellationToken失效忘记传入内层HttpClient.SendAsync检查所有await是否都传递了 tokentoken 刷新后请求仍用旧 token鉴权头写死在DefaultRequestHeaders改用DelegatingHandler动态设置鉴权头6.2 我踩过的几个坑这里有三个坑每一个都花了我不少时间写出来帮大家避开。第一个坑是枚举反序列化的大小写问题。API 返回的枚举值都是小写比如completed而 C# 枚举成员我定义成Completed。直接反序列化会失败。我一开始用JsonStringEnumConverter加[EnumMember(Value completed)]搞定但记得JsonStringEnumConverter默认要求字符串完全匹配如果你不确定服务端返回的大小写就手动写一个自定义转换器内部用Equals(value, StringComparison.OrdinalIgnoreCase)比较一劳永逸。第二个坑是流式响应里的嵌套事件。Codex 的流式事件里response.output_text.delta只是增量文本完整的文本内容还需要自己拼接。如果业务方直接用单条事件里的文本会发现反复覆盖而不是追加。我最后提供了一个Accumulator辅助类消费流的时候自动按output_index累加文本把“拿到完整文本”这件脏事封装掉了。第三个坑是超时设置的作用域。我前面提到HttpClient.Timeout是总超时这在普通请求没问题但流式请求如果也受总超时限制长任务会被杀掉。最终我把流式请求的HttpClient.Timeout设置为Timeout.InfiniteTimeSpan然后在每个ReadLineAsync的CancellationTokenSource上加单独的超时比如 60 秒内没有新数据就算超时。这样“长期运行”和“无数据保护”两个诉求都满足了。7. 后续可以扩展的方向移植完基础版本之后我自己在计划几个扩展给你们提供点思路。第一是线程安全的连接池管理。当前CodexClient是线程安全的但内部一些配置比如自定义DelegatingHandler在多租户场景下需要按租户隔离我正在尝试用IHttpClientFactory的命名客户端机制来实现。第二是缓存。非流式响应里很多是固定结构的元数据可以加一层IMemoryCache做缓存减少实际请求量。但这要小心AI 响应可能随时变化缓存策略要谨慎只缓存完全不变化的静态信息。第三是可观测性。我给真正的生产环境接入时发现缺少链路追踪信息会让排查非常痛苦。计划加上System.Diagnostics.Activity作为内置的 OpenTelemetry 支持把每个请求的trace_id和span_id透传到 Codex 服务端。移植 SDK 这件事技术难度其实不大真正考验人的是细心和耐心。类型映射、流式处理、错误分类每一项都算不上尖端技术但组合起来就是一个 SDK 是否好用的分水岭。如果你准备移植其他 TypeScript SDK我建议你先花时间把原版的真实报文摸透再动手写代码后面会省下一大半调试时间。最后说一个经验永远把“和官方行为的一致性”放在第一位。你可以优化性能可以重新设计 API 风格但核心语义和行为不能偏离。因为你的用户很可能就是看着官方文档来的一旦行为不一致他们处理 bug 的成本会成倍上升。保持兼容、保持一致、再谈改进这才是跨语言移植最稳的节奏。