Nanocodex

前沿 OpenAI 智能体的构建模块。

安装 · 智能体 API · 论点 · 组件 · VM 支持的工具 · 评估 · 文档

安装

在 macOS 或 Linux 上安装 Nanocodex CLI：

curl -fsSL https://nanocodex.paradigm.xyz | bash

或者将 Rust SDK 添加到应用程序中：

cargo add nanocodex

在已安装的 CLI 的不同构建版本之间进行切换：

nanocodex update                 # latest stable release
nanocodex update 0.2.0           # exact release, including downgrades
nanocodex update --nightly       # latest nightly
nanocodex update --pr 50         # verified on-demand PR artifact
nanocodex update --path ./nanocodex  # trusted local binary

已下载的构建版本保留在 ~/.nanocodex/versions 下。再次运行 nanocodex update 0.2.0 将切换到缓存的二进制文件，而无需再次下载。稳定的启动器即使在旧版二进制文件处于活动状态时，也会保持 nanocodex update 可用，并且 ~/.nanocodex/current 指向所选版本。

PR 工件需要一个经过身份验证的 gh CLI 以及该 PR 已完成的按需工件工作流。

最小 API 示例

use nanocodex::{Nanocodex, OpenAi};

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, mut events) = Nanocodex::builder(openai)
    .instructions(
        "You are a Rust coding agent. Make focused changes, preserve unrelated work, \
         and run relevant tests before finishing.",
    )
    .workspace(std::env::current_dir()?)
    .build()?;

let event_task = tokio::spawn(async move {
    while let Some(event) = events.recv().await {
        eprintln!("event {}: {:?}", event.seq, event.kind);
        if event.kind.is_terminal() {
            break;
        }
    }
});

// Alternative: stream this turn's response as it arrives:
// use futures_util::StreamExt;
// use nanocodex::agent::events::{AgentEventData, AssistantEvent};
// let mut turn = agent.prompt("Find and fix the failing parser test.").await?;
// while let Some(event) = turn.next().await {
//     if let AgentEventData::Assistant(AssistantEvent::Delta(delta)) = event.data()? {
//         print!("{}", delta.text);
//     }
// }
let result = agent
    .prompt("Find and fix the failing parser test.")
    .await?
    .await?;

event_task.await?;
println!("{}", result.final_message());

第一个 await 接受并处理提示。第二个等待其输入的 TurnResult。后续提示会自动复用代理保留的历史记录、WebSocket、工具、shell 会话和提示缓存身份。 agent.clone() 是同一会话的低成本句柄；独立返回的 AgentEvents 流是会话范围的事件流。

Nanocodex 支持 gpt-5.6-sol（默认）、gpt-5.6-terra 和 gpt-5.6-luna。在创建代理时，使用 .model(Model::Terra) 或 .model(Model::Luna) 选择模型。该模型对于该线程是固定的：稍后切换会使提供商检查点失效，并需要低效地重放完整的保留上下文。

使用命名空间模型标识符的 API 密钥 HTTPS OpenAI 路由网关可以设置 NANOCODEX_MODEL_ID_PREFIX。例如，前缀为 openai 会在线路上发送 openai/gpt-5.6-sol，同时在 Nanocodex 内部保留 Sol 的类型化行为、定价、压缩和快照身份。这不会添加备用提供商或任意模型接口。

语音：设备或 Unix 管道

非 TUI 桌面示例直接在 Rust 中拥有默认麦克风和扬声器，使用与生产 TUI 相同的 VoiceSessionBuilder：

nanocodex auth login # once; shares ~/.codex/auth.json with Codex
cargo run -p nanocodex-examples --bin voice

下层适配器将设备和媒体所有权置于 Nanocodex 之外。它从标准输入读取 24 kHz 单声道 PCM16 小端音频，将相同格式写入标准输出，并将转录文本和代理事件保留在标准错误输出中：

cargo run -p nanocodex-examples --bin realtime-pipe < microphone.pcm > speaker.pcm

# Equivalently, compose any live capture/decoder and playback/encoder:
capture-s16le | cargo run --quiet -p nanocodex-examples --bin realtime-pipe | play-s16le

两者均保留一个编码代理会话。空闲时，口头请求会启动工作；在该工作期间收到的后续请求，会在下一个安全的模型边界处原子性地引导当前活动轮次。两者均使用共享的 Codex/ChatGPT 订阅认证，而非 API 密钥。设置 NANOCODEX_AUTH_FILE 以覆盖正常的 Codex 凭证路径。

论点

小而精的构建模块

当每个组件都有明确的负责人和自身有用的 API 时，代理基础设施更容易理解和复用。OpenAI 客户端应能在没有代理循环的情况下工作。工具应能在没有 CLI 的情况下工作。高层代理应组合这些组件，而不是隐藏它们的另一套实现。

Nanocodex 做出少量审慎的选择——Rust、Tower、类型化协议、拥有的生命周期状态以及构建器 API——然后保持边界的简单。

模型与测试框架是协同设计的

我们并不试图超越前沿模型和 Codex 已经明确表达的行为。上下文管理、AGENTS.md、压缩、缓存标识、工具形状、继续、重连重放、取消以及进程清理是面向模型的契约的一部分。

Nanocodex 将这些不变量带入一个更小、以库为先的 API，同时将应用策略留给调用者。

证据优于直觉

代表性 cargo bench 工作负载、OpenTelemetry 追踪、差分测试以及端到端评估确保测试框架的可靠性。目标很简单：正常的智能体轮次应受限于模型和网络延迟，且 token 使用量和预估的美元成本应与结果在同一类型化边界处可见。

组件

nanocodex                         Alloy-style facade and prelude
├── agent                         nanocodex-agent
│   ├── oai                       nanocodex-oai-api
│   └── tools                     nanocodex-tools
│       └── macros                nanocodex-tools-macros
├── oai                           nanocodex-oai-api
├── tools                         nanocodex-tools
└── observability                 nanocodex-observability (optional)

该门面提供了规范化的通用导入。每个下层 crate 也被设计为可直接使用，而无需导入上层编排层。

`nanocodex`

薄门面在 crate 根处重新导出黄金代理路径，并将详细 API 置于 nanocodex::agent、nanocodex::oai 和 nanocodex::tools 之下。其预lude 仅包含构建代理所需的常见类型。

门面指南 · API 文档

`nanocodex-agent`

包含完整生命周期的特性：一个自有的私有驱动、一个廉价的克隆 Nanocodex 句柄、类型化的 Turn 和 TurnResult 值，以及一个可选的事件流。它拥有提示词排序、工具循环、AGENTS.md 发现、压缩时机、取消、快照，以及通过 spawn、 fork 和 fork_from 实现的分支。

调用者从不将之前的消息、响应 ID 或工具结果传回给智能体。

智能体指南 · API 文档

`nanocodex-oai-api`

完整的 OpenAI 边界：API 密钥和 ChatGPT 身份验证、类型化的 Responses 协议值、持久化的 WebSocket 传输、客户端拥有的上下文、延续和重放、自动定价，以及通用的 Tower 客户端。

其独立的 OpenAi -> Session -> ResponseTurn -> Response 路径提供托管对话，而不采用智能体策略。自定义的 Tower 层和服务保持具体且可命名——无需装箱或全局客户端。

OpenAI API 指南 · API 文档

`nanocodex-tools`

面向模型的工具运行时：Tool 契约、异构 Tools 注册表、标准工作区工具、shell 与进程生命周期、Code Mode、延迟 tool_search、远程分发以及 MCP。MCP 在原生目标上始终可用。

应用程序可以直接实现 Tool，或使用重新导出的 #[tool] 宏。独立的 nanocodex-tools-macros 包仅用于 Rust 的过程宏边界。

工具指南 · API 文档

`nanocodex-observability`

针对已通过代理流动的数据，提供应用自有的追踪和 OpenTelemetry 配置。它在不更改核心运行时路径的情况下，提供结构化的生命周期、模型、工具、用量、成本、缓存和延迟遥测数据。

启用该外观的 observability 功能，或直接依赖该组件。

可观测性指南 · API 文档

实验性组件

公共契约仍在完善中的组件位于 crates/experimental/：

包	职责
`nanocodex-voice`	桌面 GPT Realtime 音频和可复用的语音到代理生命周期
`nanocodex-vm`	VM 生命周期和镜像，以及保留的基于来宾的工作区工具
`nanocodex-eval`	基于 VM 的评估、规范验证、持久化证据以及实时标准 Codex 差异分析

CLI 是这些 crate 的消费者。语音和基于 VM 的工具仍然是针对常规代理会话的稳定库契约之上的薄层、可选适配器；基于 VM 的执行对于基准评估命令是强制性的。

CLI 和语言绑定

CLI/TUI、Python 包、Node/浏览器包、React 绑定和示例都是同一自有会话 API 的薄层消费者。它们不定义第二个代理协议。

示例 · JavaScript · Python · Web

基于 VM 的工具

常规 TUI 和一次性会话默认保留主机工作区工具。它们也可以将 exec_command、write_stdin、apply_patch 和 view_image 通过一个保留的 VM 进行路由：

just build-vm-guest
nanocodex \
  --vm .nanocodex/vm/session-rootfs.ext4 \
  --vm-guest-runtime target/aarch64-unknown-linux-musl/debug/nanocodex-vm-guest \
  --vm-workspace /app
nanocodex run "inspect the repository" \
  --vm .nanocodex/vm/session-rootfs.ext4 \
  --vm-guest-runtime target/aarch64-unknown-linux-musl/debug/nanocodex-vm-guest \
  --vm-workspace /app

目录根目录也可以包含 /usr/local/bin/nanocodex-vm-guest。请参阅 VM 指南以了解镜像准备、生命周期、出口流量、Linux 要求以及 macOS 签名。

文档

许可证

根据以下任一许可证授权：

Apache License, Version 2.0
MIT License

供您选择。