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 提供輕量級綁定。它讓開發者無需撰寫編排膠水程式碼，即可將功能完整的程式碼助理嵌入任何產品。