震惊！17KB代码、16MB内存、26MB二进制 —— 这个Rust编码Agent把“极简“做到了极致

震惊！17KB代码、16MB内存、26MB二进制 —— 这个Rust编码Agent把“极简“做到了极致

在AI编程工具动辄几百MB内存占用、基于Electron或Node.js构建的当下，一个由Rust编写的编码Agent正以惊人的性能数据颠覆行业认知：仅约17,000行代码、26MB二进制体积、平均16MB内存占用（峰值24MB），它就是 zerostack —— 一个受 pi 和 opencode 启发、为追求极致效率而生的极简编码Agent。

如果你受够了JavaScript系工具空闲时还要吃掉2% CPU、工作时飙升至20%的“资源黑洞“，zerostack将彻底刷新你对AI编程工具的认知边界。

一、项目介绍：当“极简“成为一种设计暴力

zerostack 是由 gi-dellav 团队用 Rust 构建的极简编码 Agent。它的核心定位不是“功能最全“，而是在功能完备的前提下，将资源占用压缩到物理极限。

1.1 性能对比：数据不会说谎

指标zerostackopencode 等 JS 系 Agent代码量~17k LoC数十万行二进制体积26MB数百MB内存占用（平均/峰值）~16MB / ~24MB~300MB / ~700MBCPU空闲占用0.0%~2%CPU工作占用~1.5%~20%

这组数据在 Intel i5 7代处理器上测得。zerostack 用 Rust 的零成本抽象和精细内存管理，实现了比传统方案低20倍的内存占用和低13倍的CPU消耗。这不是优化，这是降维打击。

1.2 核心功能一览

尽管追求极简，zerostack 并未在功能上妥协：

• 多模型支持：OpenRouter（默认）、OpenAI、Anthropic、Gemini、Ollama，以及任意自定义 Provider

• 标准工具集：完整的文件读写、编辑、Bash执行、Grep搜索、文件查找等编码Agent标准工具

• 五级权限系统：从“每个操作都询问“到“完全自动执行“，支持按工具、按路径glob/regex细粒度配置

• 会话管理：保存/加载/恢复会话，自动压缩历史以适配上下文窗口

• 终端UI：基于crossterm的自定义TUI，支持Markdown渲染、鼠标选择/复制、滚动回溯、推理过程可见性切换

• Prompt系统：内置 code、plan、review、debug、ask、brainstorm 等模式，运行时切换无需管理Skills

• MCP支持：连接MCP服务器扩展工具能力（编译时特性）

• 集成Exa搜索：内置WebFetch和WebSearch工具

• 循环任务：Ralph Wiggum loops支持长周期任务迭代

• Git Worktrees：分支级任务隔离，/worktree 命令一键切换

• ACP协议：支持Agent Communication Protocol，Zed等编辑器可直接连接

• 持久化记忆：跨会话的Markdown记忆系统（memory特性）

• 子Agent：并行子Agent用于代码库探索

• ARCHITECTURE.md：项目级架构文档注入，为所有Agent提供共享上下文

二、设计哲学：每一行代码都在为“减法“服务

zerostack 的设计哲学可以概括为一句话：“做减法，直到不能再减为止，然后让剩下的部分以最高效率运转。”

2.1 架构极简：单Crate，无Workspace

zerostack 拒绝 Rust 项目中常见的 workspace 多crate架构，选择单crate、约17k行代码的紧凑结构。所有源码集中在 src/ 目录下：

路径职责src/main.rs入口、CLI分发、模式路由src/cli.rsclap 派生式参数解析src/provider.rsLLM Provider抽象（类型擦除枚举）src/agent/Agent生命周期、系统Prompt、11个工具实现src/session/会话状态、自动压缩、存储src/permission/安全：glob+regex双层规则、Doom-loop检测src/ui/自定义TUI（crossterm，无ratatui）src/context/上下文：Prompt主题、AGENTS.md/ARCHITECTURE.md加载src/config/配置加载（TOML/JSON）src/extras/特性门控扩展：loop、mcp、acp、memory、subagents等

2.2 自定义TUI而非ratatui

团队刻意不采用ratatui，而是基于crossterm从零构建TUI。这避免了widget树的开销，保持二进制最小化。项目自建了行缓冲区、Markdown渲染器、滚动/选择系统。Renderer直接操作viewport buffer，通过crossterm绘制命令输出。

2.3 类型擦除枚举，拒绝动态分发

在 src/provider.rs 中，zerostack 使用 AnyClient / AnyModel / AnyAgent 枚举来包装rig框架的各Provider客户端，而非 dyn CompletionModel trait对象。这避免了vtable的生命周期问题，枚举匹配比动态分发更快。

2.4 单线程Tokio默认

zerostack 默认使用 #[tokio::main(flavor = “current_thread”)]，除非显式启用 multithread 特性。对于CLI工具而言，单线程足以处理用户输入和LLM流式响应，避免了多线程调度开销。

2.5 特性门控：核心不膨胀

loop、mcp、acp、memory、subagents、git-worktree、archmd 全部是编译时特性。默认构建只包含核心功能，用户按需开启扩展，确保二进制始终精简。

2.6 双层权限：快路径+精确匹配

权限系统采用 glob（快速路径）+ regex（复杂模式） 的双层架构。glob处理常见规则，regex处理精确匹配。同时内置 Doom-loop检测：相同工具调用重复3次以上会触发警告或拒绝，防止失控Agent的破坏。

三、详细教程：从安装到精通

3.1 安装

方式一：一键脚本（推荐）

curl -fsSL https://raw.githubusercontent.com/gi-dellav/zerostack/main/install.sh | bash

方式二：Nix（适合NixOS用户）

直接运行

nix run github:gi-dellav/zerostack

安装到profile

nix profile install github:gi-dellav/zerostack

方式三：Cargo（Rust开发者）

默认特性：loop, git-worktree, mcp, subagents, archmd

cargo install zerostack

全特性

cargo install zerostack –all-features

指定特性

cargo install zerostack –features acp,memory,multithread

可选：沙箱模式

如需 –sandbox 保护，安装 bubblewrap：

Debian/Ubuntu

apt install bubblewrap

Fedora

dnf install bubblewrap

Arch

pacman -S bubblewrap

3.2 快速启动

设置API Key（默认使用OpenRouter）

export OPENROUTER_API_KEY=“your-api-key”

交互式会话（默认prompt: code）

zerostack

无色彩TUI

zerostack –no-color

单次提问模式

zerostack -p “Explain this project”

继续上次会话

zerostack -c

指定Provider和模型

zerostack –provider openrouter –model deepseek/deepseek-v4-flash

首次运行后，执行 /prompt autoconfig 可启动交互式配置向导，引导你完成所有设置。

3.3 配置详解

zerostack 读取配置文件，优先级如下：

• $ZS_CONFIG_DIR/config.toml 或 config.json

• ~/.config/zerostack/config.toml 或 config.json

• ~/.local/share/zerostack/config.toml 或 config.json

macOS 上路径为 ~/Library/Application Support/zerostack/。

推荐TOML格式（对权限规则更友好）：

provider = “openrouter” model = “deepseek/deepseek-v4-flash” max_tokens = 16384 temperature = 0.7 context_window = 128000 reserve_tokens = 16384 keep_recent_tokens = 10000 compact_enabled = true default_prompt = “code” default_permission_mode = “standard” show_tool_details = 3

[quick_models.fast] provider = “openai” model = “gpt-4o-mini”

[custom_providers.local-vllm] provider_type = “openai” base_url = “http://localhost:8000/v1” api_key_env = “VLLM_API_KEY”

[permission] “*” = “ask”

[permission.read] “/*.rs” = “allow” “” = “ask”

[permission.bash] “cargo test” = “allow” “rm **” = “deny”

[permission.write] “src//*.rs” = “allow” “” = “ask”

关键配置项说明：

配置项说明context_window会话上下文窗口大小（默认128k）reserve_tokens触发压缩前保留的token数keep_recent_tokens压缩时保留的最近token预算compact_enabled自动对话压缩（防止超出上下文）deny_repeated_reads禁止重复读取同一文件段（默认true）edit_systemsimilarity（默认，SEARCH/REPLACE）或 hashedit（CRC-32标签编辑）show_tool_detailsTUI中显示工具结果预览的行数

3.4 权限系统实战

zerostack 提供五种权限模式，通过CLI标志或 /mode 命令切换：

模式标志行为restrictive-R / –restrictive每个操作都询问readonly–read-only只允许读操作guarded–guarded读自动允许，写/编辑/执行询问standard（默认）CWD内路径工具自动允许，安全bash自动允许，外部路径和未知命令询问yolo–yolo全部允许，但破坏性bash命令（rm/dd等）仍询问

细粒度配置示例：

[permission] “*” = “ask” # 默认询问

[permission.write] “/*.rs” = “allow” # .rs文件自动允许写入 “/*.md” = “allow” # .md文件自动允许写入 “**” = “ask” # 其他文件询问

[permission.bash] “cargo test” = “allow” # 测试自动允许 “cargo check” = “allow” # 检查自动允许 “git status” = “allow” # git状态自动允许 “rm **” = “deny” # 删除操作拒绝 “sudo **” = “ask” # sudo询问

会话白名单：一旦你在会话中批准了某个操作，zerostack会记住这个决定，不再重复询问。

3.5 Prompt系统：无需Skills的上下文切换

zerostack 内置多种Prompt模式，运行时通过 /prompt 切换：

Prompt用途code（默认）编码模式，完整文件和bash工具访问，TDD工作流plan仅规划——探索并生成计划，不写代码review代码审查——检查正确性、设计、测试和影响debug调试模式——先找根因再提修复方案ask只读模式——仅允许read/grep/find_filesbrainstorm设计模式——探索想法并呈现设计，不写代码frontend-design前端设计模式——生产级UI设计review-security安全审查模式——查找可利用漏洞simplify代码简化模式——优化清晰度，不改变行为write-promptPrompt编写模式——创建和优化Agent Prompt

自定义Prompt：将Markdown文件放入 ~/.local/share/zerostack/prompts/，即可通过 /prompt 文件名 调用。

Prompt指令：自定义Prompt文件首行可写 %%mode=standard 等，自动切换安全模式。

3.6 会话管理

列出所有会话

/session

保存当前会话

/session save my-feature

加载特定会话

zerostack –session my-feature

恢复最近会话

zerostack -c

浏览并选择会话

zerostack -r

会话自动保存到 $XDG_DATA_HOME/zerostack/sessions/。zerostack 会自动压缩历史消息，当token数接近上下文窗口时，旧消息会被摘要化并丢弃，保留摘要前缀和最近的完整对话。

3.7 高级功能

3.7.1 循环任务（Loop）

适合长周期迭代任务：

启动循环

/loop Implement the user authentication system

查看状态

/loop status

停止循环

/loop stop

无头模式（CI/CD适用）：

zerostack –loop –loop-prompt “Refactor the API” –loop-max 10 –loop-run “cargo test”

3.7.2 Git Worktrees

分支级任务隔离，不污染主工作区：

创建并进入worktree

/worktree feature-x

工作…完成后合并回main

/wt-merge

或直接退出不合并

/wt-exit

3.7.3 并行子Agent（/btw）

不中断主Agent的情况下并行提问：

快速侧问（只读工具）

/btw How does the error handling work in this module?

指向特定文件

/btw @src/main.rs how does the auth flow work?

/btw 会fork当前上下文，使用4个只读工具回答，不写入对话历史，token消耗在状态栏单独显示。

3.7.4 输入队列

Agent运行时你可以继续输入，文本会自动排队，当前任务完成后依次执行：

/queue ls # 查看排队输入 /queue clear # 清空队列 /queue pop # 移除最后一个

3.8 ACP模式（编辑器集成）

启用 acp 特性后，zerostack可作为ACP Agent服务器，供Zed等编辑器连接：

stdio模式（编辑器作为父进程启动）

zerostack –acp

TCP模式

zerostack –acp –acp-host 0.0.0.0 –acp-port 7243

四、最佳实践：榨干zerostack的每一分性能

4.1 配置最佳实践

1. 使用TOML而非JSON配置权限

TOML的表结构天然适合zerostack的权限规则，避免JSON的深层嵌套：

permission-allow = { read = [“src/”, “tests/”] } permission-ask = { bash = [“rm ”, “docker ”] } permission-deny = { write = [“/etc/”, “/usr/”] }

2. 为不同项目创建独立配置

使用 ZS_CONFIG_DIR 环境变量为不同项目指定配置：

项目A

export ZS_CONFIG_DIR=~/projects/a/.zerostack zerostack

项目B

export ZS_CONFIG_DIR=~/projects/b/.zerostack zerostack

3. 合理设置上下文窗口

如果你使用的大模型支持128k上下文，保持默认即可。如果使用较小模型，调低 context_window 和 reserve_tokens：

context_window = 32000 reserve_tokens = 4096 keep_recent_tokens = 5000

4. 启用hashedit编辑系统（大文件场景）

对于频繁编辑大文件的场景，hashedit 比 similarity 更省token：

edit_system = “hashedit”

hashedit使用CRC-32行标签和文件级CAS令牌，无需复制旧文本，删除和大规模编辑时token效率显著提升。

4.2 安全最佳实践

1. 默认使用guarded模式探索新项目

进入陌生代码库时，先用 –guarded 模式，确认Agent行为符合预期后再切换到 standard 或 yolo。

2. 细粒度控制bash权限

永远不要全局允许 rm 或 sudo：

[permission.bash] “rm **” = “deny” “sudo **” = “ask” “dd **” = “deny” “mkfs **” = “deny”

3. 使用sandbox保护系统

zerostack –sandbox

bubblewrap会为每个bash命令创建隔离环境，防止意外或恶意破坏。

4. 利用ARCHITECTURE.md建立项目上下文

在仓库根目录创建 ARCHITECTURE.md（或启用 archmd 特性），描述项目架构。zerostack会自动将其注入系统Prompt，让所有Agent（包括子Agent）共享核心知识。

4.3 工作流最佳实践

1. Plan → Code → Review 三段式工作流

第一步：规划

/prompt plan “设计一个用户认证系统，包括JWT、刷新令牌、角色权限”

第二步：编码

/prompt code “按照PLAN.md实现认证系统”

第三步：审查

/prompt review “审查src/auth/目录下的所有代码”

2. 利用Git Worktrees进行并行开发

主分支保持干净

/worktree feature-a

… 工作 …

/wt-merge

/worktree feature-b

… 工作 …

/wt-merge

3. 长任务使用Loop + 验证命令

zerostack –loop –loop-prompt “优化所有SQL查询” –loop-run “cargo test –test integration” –loop-max 5

4. 会话命名规范

/session save 20250610-refactor-auth /session save 20250610-fix-race-condition

便于后续检索和恢复。

4.4 性能最佳实践

1. 默认构建足够日常使用

除非需要ACP、Memory或子Agent，否则使用默认构建：

cargo install zerostack

2. 使用mimalloc

zerostack已内置mimalloc作为全局分配器，无需额外配置即可获得最佳内存性能。

3. 限制工具详情显示

show_tool_details = 3

减少TUI渲染负担，尤其在低性能终端。

五、综合评价：谁应该选择zerostack？

5.1 适合人群

• 资源敏感型开发者：在老旧笔记本、云服务器、或同时运行多个Agent的场景下，zerostack的低资源占用是巨大优势

• Rust生态开发者：Rust项目用Rust工具，类型系统和内存安全理念一致

• 终端/CLI爱好者：自定义crossterm TUI响应极快，无Electron的迟滞感

• 安全偏执者：五级权限+glob/regex细粒度控制+Doom-loop检测，给予最大控制权

• 多模型切换用户：OpenRouter默认，一键切换OpenAI/Anthropic/Gemini/Ollama

5.2 不适合人群

• 纯GUI用户：zerostack是终端工具，无图形界面

• Windows主力用户：官方明确说明Windows支持未测试

• 开箱即用型用户：相比opencode等，zerostack需要更多手动配置（但 /prompt autoconfig 已大幅改善）

5.3 与竞品对比

维度zerostackopencodeClaude Code语言RustTypeScript/NodeTypeScript内存占用~16MB~300MB~200MB+二进制体积26MB数百MB数百MB权限控制五级+glob/regex基础基础编辑系统similarity/hashedit标准标准自研TUI是（crossterm）否否MCP支持编译时特性内置内置ACP支持编译时特性否否开源协议GPL-3.0视项目而定闭源

5.4 总结

zerostack 证明了**“极简“不等于“简陋”**。它用约17k行Rust代码、26MB二进制、16MB内存，构建了一个功能完备、安全可控、性能碾压同类产品的编码Agent。它的设计哲学——单crate架构、类型擦除枚举、自定义TUI、特性门控扩展、双层权限——处处体现着对资源效率的极致追求。

在AI工具日益臃肿的今天，zerostack 像一把精密的手术刀：没有多余的装饰，但每一毫米都经过淬炼。如果你相信代码应该像诗歌一样精简，工具应该像匕首一样锋利，zerostack 值得你放入工具箱的核心位置。

项目地址：https://github.com/gi-dellav/zerostack Matrix聊天室：项目README内提供链接 许可证：GPL-3.0-only