跨语言移植手记：把 TypeScript 的 Codex SDK 请进 .NET 世界

这事儿得从我们在 HagiCode 项目里遇到的一个实际困境说起。我们需要在一个纯 .NET 环境------包括后端服务和桌面客户端------里调用 Codex 的能力。Codex 是 OpenAI 那个挺实用的 AI Agent 命令行工具，官方给了 TypeScript SDK，封装在 @openai/codex 包里。它干活的方式是调用 codex exec 命令，然后解析吐出来的 JSONL 事件流。

直接想法？在 .NET 进程里启动 Node.js 运行时去跑这个 TypeScript SDK，通过进程间通信搭个桥。但稍微琢磨一下就知道，这路子太折腾了：引入巨大的运行时依赖、跨进程通信的稳定性和性能损耗、还有那复杂的错误处理......一套下来，维护成本怕是要起飞。

所以，我们决定走另一条路：把官方的 TypeScript SDK 完整地"移植"成一份原生的 C# SDK。 说是"移植"，其实更像是一次在两个不同语言生态和设计哲学之间的翻译与重建。两种语言的"脾气"确实不太一样，关键是怎么让它们在 .NET 的世界里，依然能把活儿干得漂亮。

一、架构设计的"神"与"形"

动手之前，得先吃透 TypeScript SDK 的骨架。它的核心层次很清晰：

Codex (入口类) → CodexExec (执行器，管理子进程) → Thread (对话线程) → run()/runStreamed() (执行) 和事件流解析

我们的目标不是简单翻译代码，而是让 C# SDK "神似"而非"形似"。也就是说，对外暴露的 API 要保持一致，让熟悉 TypeScript 版本的开发者能零成本上手；但在内部实现上，得充分利用 C# 的语言特性和 .NET 生态的优势。

二、类型系统的映射：从灵活到严谨

这是最基础也最考验细节的工作。TypeScript 的类型系统以灵活著称，C# 则更强调严谨和确定性。怎么找到那个合适的映射点？

先看一个表格，这是两种语言核心类型映射的对照表：

TypeScript 类型	C# 类型	映射说明
`interface` / `type`	`record`	用 `record` 实现不可变的数据传输对象（DTO），契合函数式编程风格。
`string` \| `null`	`string?`	直接映射为 C# 8.0 的可空引用类型，语义清晰。
`boolean` \| `undefined`	`bool?`	用可空布尔值表示"未定义"状态。
`AsyncGenerator<T>`	`IAsyncEnumerable<T>`	.NET Core 3.0+ 的标准异步流处理接口，完美对应。

事件类型的处理是个典型例子。TypeScript 用联合类型（Union Type）来定义多种事件结构：

typescript 复制代码

export type ThreadEvent =
  | ThreadStartedEvent
  | TurnStartedEvent
  | TurnCompletedEvent
  // ... 其他事件

这种"或"的关系，在 C# 里最自然的映射就是继承层次结构 + 模式匹配：

csharp 复制代码

// 抽象基类，包含一个用于运行时类型识别的鉴别器属性
public abstract record ThreadEvent(string Type);

// 具体事件类型，继承自基类，并携带各自的数据
public sealed record ThreadStartedEvent(string ThreadId) : ThreadEvent("thread.started");
public sealed record TurnStartedEvent() : ThreadEvent("turn.started");
public sealed record TurnCompletedEvent(Usage Usage) : ThreadEvent("turn.completed");
// ...

// 使用时，通过模式匹配优雅地分派
await foreach (var @event in thread.RunStreamedAsync(...))
{
    switch (@event)
    {
        case TurnCompletedEvent completed:
            Console.WriteLine($"本轮完成，消耗Token: {completed.Usage.InputTokens}");
            break;
        // ... 处理其他类型
    }
}

用 record 而非 class，是因为事件数据本质上是不可变的快照；用 sealed 则明确表示不会有进一步的派生，有利于编译器优化。

三、核心难点的攻克

1. 事件解析器：从 JSON.parse 到 JsonDocument

TypeScript 里解析事件流就是一行 JSON.parse(line)，但在 C# 里需要更精细地控制资源。我们用 System.Text.Json 实现了解析器：

csharp 复制代码

public static ThreadEvent Parse(string line)
{
    // 用 using 确保 JsonDocument 在使用后立即释放非托管资源
    using var document = JsonDocument.Parse(line);
    var root = document.RootElement;
    var type = GetRequiredString(root, "type", "event.type");

    // 基于 type 字段进行模式匹配
    return type switch
    {
        "thread.started" => new ThreadStartedEvent(
            GetRequiredString(root, "thread_id", "...")),
        "turn.completed" => new TurnCompletedEvent(
            ParseUsage(GetRequiredProperty(root, "usage", "..."))),
        // ... 处理其他已知类型
        // 未知类型：克隆一份数据保留下来，因为 document 即将被释放
        _ => new UnknownThreadEvent(type, root.Clone())
    };
}

这里的 root.Clone() 是个关键细节：JsonDocument 被 using 包裹，一旦离开作用域其内存就会被回收。对于未知的事件类型，我们需要保留原始数据，所以必须创建一个深层克隆。

2. 进程管理与取消机制

这是两个 SDK 差异最大的地方，也是移植工作的核心。

TypeScript 使用 Node.js 的 child_process.spawn()，配合 AbortSignal 实现优雅取消：

typescript 复制代码

const controller = new AbortController();
const child = spawn(executablePath, args, { signal: controller.signal });
// 稍后 controller.abort() 即可取消进程

C# 里，我们使用 System.Diagnostics.Process，配合 CancellationToken：

csharp 复制代码

// 配置进程启动信息，关键是重定向标准输入输出
var startInfo = new ProcessStartInfo
{
    FileName = _executablePath,
    RedirectStandardInput = true,
    RedirectStandardOutput = true,
    RedirectStandardError = true,
    UseShellExecute = false, // 必须为 false 才能重定向流
    CreateNoWindow = true    // 不显示命令行窗口
};

using var process = new Process { StartInfo = startInfo };
process.Start();

// 异步读取输出的方法，接受 CancellationToken
public async IAsyncEnumerable<string> RunAsync(
    CodexExecArgs args,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    // 启动后，需要手动管理三个流的读写
    _ = Task.Run(() => WriteStdinAsync(cancellationToken), cancellationToken);

    // 逐行读取 Stdout
    while (!cancellationToken.IsCancellationRequested)
    {
        var line = await process.StandardOutput.ReadLineAsync();
        if (line == null) break;
        yield return line;
    }

    // 如果取消被触发，需要主动终止进程树
    if (cancellationToken.IsCancellationRequested)
    {
        try
        {
            // 杀掉整个进程树，避免残留子进程
            process.Kill(entireProcessTree: true);
        }
        catch { /* 忽略 Kill 过程中的异常 */ }
    }
}

可以看到，C# 版本需要更细致地管理流和进程生命周期，CancellationToken 扮演了和 AbortSignal 类似的角色，但集成在 .NET 的异步编程模型里。

四、一些实践中的体悟

API 一致性优先于实现细节 ：用户在意的不是你内部用 async/await 还是 Task，而是调用 thread.RunAsync() 的感觉是否和 TypeScript 版一样顺手。因此，我们尽量保持了命名、参数顺序和行为的一致性。
资源清理是"有始有终"的责任 ：.NET 是托管运行时，但对进程、文件句柄等非托管资源必须显式管理。我们让 CodexExec 实现 IDisposable，OutputSchemaTempFile 实现 IAsyncDisposable，确保临时文件和子进程在任何情况下都能被清理干净。
拥抱平台差异 ：TypeScript 版会自动在 node_modules 里寻找 Codex 的可执行文件。但在 .NET 世界里，这是不合理的。我们选择通过环境变量或配置项让用户显式指定路径，虽然多了一步配置，但更符合 .NET 应用的部署习惯，也避免了隐含的副作用。这算是一种"因地制宜"吧。

五、总结

将一个成熟的 TypeScript SDK 移植到 C#，远不是逐行翻译那么简单。它要求你深入理解两种语言的设计哲学：TypeScript 的灵活与 JavaScript 生态的特性（如 AbortSignal、AsyncGenerator），如何在 C# 这个更强调严谨、可控和编译时检查的环境中找到最对等的实现方案。

整个过程，是一次对两个技术世界异同的深度探索。最终交付的，不是一个完美的"复制品"，而是一个 "神似"的、能在 .NET 生态里安家落户的好公民 。如果你也在进行类似的跨语言移植，我的建议是：先吃透架构，再攻克难点，最后用完整的测试用例锁死行为一致性。这事急不得，但走通了，收获绝对不止一个 SDK 本身。

项目免费体验： www.jnpfsoft.com/?from=001YH...