gakonst/nanocodex

Nanocodex – 专为 OpenAI 驱动的代码助手打造的库优先 SDK

是什么 – Nanocodex 是一个 无头 Rust 库（附带 JavaScript/Node、浏览器和 Python 的绑定），实现了 gpt-5.6-sol 系列的完整 OpenAI Responses 交互循环。它提供了一个可嵌入的 代码助手，其生命周期（提示排序、工具调用、代码执行、子进程清理、快照、分支等）由库自身管理，因此应用程序无需重新实现任何底层逻辑。

为何重要 – 围绕大型语言模型构建可靠的“代码助手”通常需要拼接以下组件：

• 提示排序队列
• 模型的持久 WebSocket 连接
• 重试/压缩逻辑
• 工具执行沙箱
• 会话历史、快照和子进程的干净关闭

Nanocodex 一次性完成所有这些工作，并暴露一个极小、类型安全的 API。使用者可以专注于产品 UI、持久化或自定义工具，而非重复实现编排运行时。

---

核心功能

功能	你将获得
类型安全的回合处理	prompt() 返回一个 Turn 未来对象；该回合还会生成一个可选的类型化事件流（例如工具调用、使用统计）。
保留的会话历史	该助手维护已完成响应的权威 FIFO 历史记录；新提示仅包含增量变化。
内置工具生态系统	工作区工具（文件操作、Shell 执行、补丁应用、图像查看）、网络搜索、图像生成，以及一个 代码模式 JavaScript 沙箱，允许模型运行任意 JS 并通过 await tools.<name>(...) 调用工具。
分支与快照	spawn()、fork()、fork_from() 可创建新助手或从检查点恢复，无需复制整个进程状态。
持久化层（可选）	仅追加日志，支持 SQLite/Postgres 后端；提供重放、去重和崩溃安全恢复。
子助手	轻量级任务树注册表，提供可在代码模式中使用的编排原语（spawn、wait、interrupt）。
多主机支持	相同的 Rust 核心可在原生、WASM 工作线程（浏览器）或 PyO3（Python）中运行。JavaScript 绑定公开 Agent、Transport 和 Subagents，适用于 Node 或浏览器。
OpenAI 专用	直接支持 gpt-5.6-sol 系列（默认 sol，也支持 terra 和 luna）。无通用提供者抽象——该库完全掌控 Responses WebSocket 行为。

---

语言与入口点

语言	包 / crate	典型入口点
Rust	nanocodex（crate）	Nanocodex::builder(OpenAi::new(...)).build()?
JavaScript / Node	nanocodex npm 包	import { Agent, Transport } from "nanocodex/node"
浏览器 / WASM	相同 npm 包（nanocodex/browser）	Agent.create({ transport: Transport.hostManaged(...), ... })
Python	PyO3 轮子（PyPI 上的 nanocodex）	Nanocodex(api_key, instructions=...)

---

典型使用模式（Rust 示例）

let openai = OpenAi::new(std::env::var("OPENAI_API_KEY")?)?;
let (agent, _events) = Nanocodex::builder(openai)
    .instructions("You are a Rust coding agent.")
    .workspace(std::env::current_dir()?)
    .build()?

let turn = agent.prompt("Fix the failing parser test.").await?;
let result = turn.await?;               // typed TurnResult
println!("{}", result.final_message());
agent.shutdown().await?;

JavaScript（turn.result()）和 Python（agent.prompt(...).result()）中也存在相同流程。

---

何时使用 Nanocodex？

• 产品团队：构建 IDE 扩展、CI 机器人或低代码平台，需要一个可靠的“代码修复”或“代码生成”助手，而无需重新实现 OpenAI 会话循环。
• 研究原型：希望在保持核心助手稳定的同时，实验自定义工具、分支或持久化检查点。
• 全栈应用：同一助手在服务器（Rust/Node）和浏览器（WASM）中运行，为用户提供页面内代码工作区。
• 语音助手：该库已自带语音客户端；你可接入自己的音频管道，仍能享受相同的会话管理功能。

---

安装快速入门

# Rust
cargo add nanocodex

# Node (>=22.13)
npm install nanocodex

# Python（从源码检出）
uv venv --python 3.11 py/bindings/.venv
uv pip install -r py/bindings/requirements.txt maturin
py/bindings/.venv/bin/maturin develop --manifest-path py/bindings/Cargo.toml

或通过 README 中显示的一行命令获取 macOS 或 Linux 的预构建 CLI/TUI 二进制文件。

---

成熟度与状态

• Crates.io 版本已发布，并在 Linux/macOS 上通过 CI 测试。
• 核心助手、持久化层和工具 crate 稳定；浏览器专用和实验性 VM crate 标记为 未发布/实验性。
• 文档可在 docs.rs 和各 crate 的仓库内 README 中获取。
• 项目提供一系列示例（最小、生命周期、分叉、子助手、浏览器、React、Vercel 工作流），作为参考实现。

---

TL;DR

Nanocodex 提供一个 单一、类型安全、由 Rust 所有 的 SDK，处理 OpenAI 代码助手的整个生命周期——提示排序、工具执行、分支、快照和清理——同时为 JavaScript/Node、浏览器和 Python 提供轻量级绑定。它让开发者无需编写编排胶水代码，即可将功能完整的代码助手嵌入任何产品。