Zaru CLI:它能做什么,如何安装,依据它的 README

其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南

声明:Zaru 由 100monkeys AI, Inc. 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据 main 分支上的 zaru-cli README(2026 年 10 月 28 日读取)起草,并经公司审阅;这个简体中文版是英文原版指南的译文。下面每条命令都是从该 README 原样复制的,引文保留英文原文,译文附在旁边。README 没有回答的问题,我们直接说明,不做填补。

一句话概括 README:"Zaru is an AI assistant that works in your terminal. You give it a task, it asks a language model, and it runs the tools the model asks for: it reads and edits files, runs commands and fetches web pages, asking your permission first."(Zaru 是一个在终端里工作的 AI 助手。你给它一个任务,它询问语言模型,并运行模型要求的工具:读取和编辑文件、运行命令、抓取网页,事先征求你的许可。)每一步都会写进一份纯文本记录,你可以用 cat 阅读。

它清楚自己处在哪个阶段

README 说得很直接:"It is pre-alpha: there are no releases and no packages, you build it from source, and commands, files and settings can change without notice."(它处于 pre-alpha 阶段:没有发布版本,也没有软件包,需要从源码编译,命令、文件和设置可能随时变更而不另行通知。)它以 Apache-2.0 许可开源。它也不是沙箱:"Zaru acts on your machine with your user account's permissions."(Zaru 以你的用户账户权限在你的机器上操作。)在让它处理你在意的东西之前,请先读 README 的 Safety 一节。

第 1 步:检查要求

Linux。"does not build on Windows"(无法在 Windows 上编译),macOS "is not tested"(未经测试)。
Rust 1.98.1,固定在 rust-toolchain.toml 中;首次编译时由 rustup 安装。
一个 C 编译器(cc),首次编译时需要能访问 crates.io 的网络。
一个模型:Google Gemini API 密钥、一个 Ollama 服务器,或任何提供 OpenAI 兼容 chat completions API 的服务器。

第 2 步:编译并安装

git clone https://github.com/100monkeys-ai/zaru-cli.git
cd zaru-cli
cargo install --path crates/zaru-cli --locked

这会把 zaru 放到 ~/.cargo/bin。运行 zaru --version 检查它能否工作。

第 3 步:选择模型

"Zaru has no default model."(Zaru 没有默认模型。)你需要自己创建 ~/.zaru/config.toml。使用 Gemini 时,先保存密钥(从标准输入读取:粘贴后按回车,再按 Ctrl-D),然后指定模型:

zaru providers keys add gemini

[model]
default = "gemini-3.6-flash"

保存的密钥使用一把存放在操作系统钥匙串中的密钥加密。在没有钥匙串的机器上,例如服务器、WSL 或容器,把 ZARU_CREDENTIAL_KEY 设为 64 个小写十六进制字符并保存好这个值,因为 "without it, the keys you stored cannot be read again."(没有它,你保存的密钥就再也无法读取。)使用 Ollama 不需要密钥:在 [provider.default] 下写 kind = "ollama",Zaru 会连接 http://localhost:11434。使用 OpenAI 兼容服务器时,写 kind = "openai-compatible" 和它的 endpoint;如果服务器的模型列表没有给出上下文窗口,再加上 context_tokens。

第 4 步:运行一个任务

zaru "read src/main.rs and tell me what it does"

在你希望它工作的目录里运行。它会显示"不是沙箱"的提示、每次工具调用及其所做的事、答复、"counted by the provider"(由提供方统计)的令牌数,以及一条关于验证器的说明。不带参数的 zaru 则会打开交互式会话;zaru --continue 会重新打开当前目录中的上一个会话。

第 5 步:回答权限提问

在写文件、编辑文件、运行命令或抓取网页之前,Zaru 会显示这次调用将做什么,并询问 [y/N/a ...]。y 允许一次,a 在本次会话中允许同一调用,N、回车或 Esc 表示拒绝,任务继续。Ctrl-C 停止整个任务。抓取网页时会显示完整 URL,"because a URL can carry data off your machine"(因为 URL 可能把数据带出你的机器)。如果没有可以提问的终端,调用会被拒绝。默认模式是 ask;allow 会跳过你允许列表中的内容,yolo 什么都不问,README 说它 "only for a directory and a task you trust entirely."(只用于你完全信任的目录和任务。)

第 6 步:阅读记录

zaru sessions list
cat ~/.zaru/sessions/<id>/transcript.jsonl

每行一个 JSON 对象:你的任务、模型的每次答复及其请求的工具调用、每次调用是否被允许、调用返回的内容("exactly as the model was given it",与交给模型的内容完全一致)以及最终答复。保存的密钥和令牌在写入之前会被替换为占位符。

第 7 步:添加验证器

zaru init 会写出一个示例 ./zaru.toml。验证器是一条检查模型工作结果的命令:

[[validator]]
name = "test"
run = "cargo test"
expect = "exit-zero"

声明了验证器后,任务就变成一个循环:模型修改某些内容,验证器运行,失败结果返回给模型,直到全部通过或达到 runtime.max_iterations。验证器只有在你批准后才会运行,内容变化时会再次询问你;"the permission mode does not skip it."(权限模式不会跳过这一步。)

它还做不到的事

只有三种提供方可用:gemini、ollama 和 openai-compatible。"anthropic and aegis are recognised but have no client."(anthropic 和 aegis 能被识别,但还没有客户端。)
运行时等级 contained 和 linked "can be selected but are not built yet"(可以选择,但尚未实现):在每个等级下,工具调用都直接在你的机器上运行。
zaru learned 和 zaru inbox 只是占位命令。

README 尚未说明的地方

第一个发布版本或软件包何时推出。README 只说目前没有。
CLI 会话与 ask.myzaru.com 网页应用中的对话是什么关系。README 介绍了与 Carbon Forge 的连接(zaru notes tokens add),但没有提到网页应用。
还有哪些 Gemini 模型名称可用。README 只给出了一个。