Zerone（zero to one）

这是一个极简但结构完整的基底 Agent(Rust)。在2000行左右代码（不包含Tui、注释）下打造了一个非生产级的类 Claude Code / Codex / Pi 等coding agent 的最小可运行雏形:一个正确的 Agent Loop + 五个工具 + 三种 LLM 接口的流式适配 + 一个简约 TUI,没有其他。

这个仓库适用于在此项目的基础上，扩展其harness工程，制作一个属于自己的可靠的agent。而不是从零构建agent的教程，如果需要的相关教程的话，请看：abstract 内推荐的教程

同时这个仓库的docs也是我学习与实践后的总结文档，共九个，包含从零构建到后续扩展的所有历程。我同时还深度清洗并阅读了 Pi 的实现，清洗后的代码在：pi。我记录了它的优秀实现，并汇总出 7 篇文档；它们关注如何让现在的 Zerone 从一个 MVP 进化成可靠、消费级的 coding agent：docs/pi

我自己的实践：我自己也正在基于zerone与总结的文档，完成一个Pi级别的coding agent，详见：onemore

TUI / --once ◄──AgentEvent──┐
     └──AgentCommand──► Runtime(Agent Loop)
                          ├─ context/   每轮"模型看到什么"(instructions + 环境 + 历史)
                          ├─ tools/     read_file · list_dir · write_file · edit_file · run_command
                          └─ provider/  Messages(Anthropic) │ Chat Completions │ Responses(OpenAI)
                                        —— 内部只有一套消息模型,三家只是编解码方言

快速开始

cargo run                  # 首次运行生成 ~/.zerone/config.toml 模板
# 编辑全局 config.toml 选择 provider,配好 API key(或设对应环境变量)
cargo run                  # 进入 TUI
cargo run -- --once 你好    # 无界面跑一轮,最快的连通性测试
cargo run -- -p deepseek   # 临时切换 provider

发布 npm 包后也可以直接安装预编译版本，无需 Rust 工具链：

npm install --global zerone-agent
zerone

代理走 HTTPS_PROXY/HTTP_PROXY 环境变量;base_url 可指向任意兼容服务(中转、ollama、vLLM)。

按键与命令

按键	作用	命令	作用
Enter	发送	/provider [名]	列出/热切换 provider(历史保留)
行尾 \ + Enter	换行(Shift+Enter 仅部分终端;多行粘贴自动识别)	/model 名	改模型
Esc	取消当前轮 / 回底部 / 清输入	/session [ID]	列出/恢复当前 workspace 的会话
Ctrl+L	强制重绘	/clear	清空当前会话
鼠标滚轮 / 拖动	浏览终端历史 / 选择文本	/clear	清空当前会话
PgUp·PgDn / ↑·↓	滚动当前输出 / 输入历史	/help /quit	帮助 / 退出
Ctrl+C ×2	退出(任何时候有效)

结构与文档

src/message.rs   统一消息模型     src/provider/  三接口流式适配 + SSE
src/workspace.rs 文件访问唯一入口  src/event.rs   Runtime↔前端唯一契约
src/tools/       工具系统         src/runtime.rs Agent Loop 本体
src/storage.rs   全局路径 + SQLite 会话存储
src/context/     上下文组装       src/tui/       事件流的一个消费者
tests/wire.rs    三接口 mock 集成测试(不碰真实网络)

• 每个源文件头部有设计动机注释;扩展前请读 docs/:01 架构 → 02 循环 → 03 工具 → 04 提供商 → 05 上下文 → 06 加工具 → 07 加提供商 → 08a 底层扩展 → 08b 工具扩展。
• 项目摘要与学习推荐见 abstract.md。

刻意的取舍——为了更好扩展性

零 unsafe、无异步运行时(阻塞 IO + 两线程);run_command 不保留 cd 状态(有 cwd 参数);无权限/审批/记忆/MCP/子代理——它们是留给使用者的扩展作业,各篇文档结尾有挂载点分析。

配置和会话位于用户目录的 .zerone/。每个会话保存为 sessions/<uuid>.db， 并记录其 workspace；在同一路径启动 Zerone 后用 /session 查找，再用 /session ID 恢复。可设置 ZERONE_HOME 覆盖数据目录，便于测试或便携安装。

打包与发布 npm

本机构建即可，当前zerone只支持windows。

.\scripts\package-npm.ps1 -Pack
node .\dist\npm\package\bin\zerone.js --help

npm publish zerone-agent-0.1.0.tgz --access public

版本默认读取 Cargo.toml，也可以在手动运行 workflow 时覆盖包名和版本。npm 包只包含 Node 启动器与预编译二进制，运行时仍是同一个 Rust zerone 进程。 所以发布后续版本只需更新 Cargo.toml 版本

License

MIT

学ai，上L站

linux.do