Bash 优先，原生移植，语义一致

bash-agent

一个面向真实编码工作的 AI Agent Runtime。Bash 版本保持零运行时依赖，C、Go、Rust 版本对齐同一套 session、tool、display queue、events.jsonl 和 stream-json 行为。

快速开始查看文档

0 runtime Bash 版无需 Node/Python

4 ports Bash / C / Go / Rust

events.jsonl 人类展示和机器输出解耦

~/workspace · bash-agent

# install

$ brew install lloydzhou/tap/bash-agent

installed: bash-agent cagent goagent rustagent tcode

# human display

$ bash-agent "检查这个 PR 的风险"

tool: Read · Grep · Bash

done: session saved, cache stats updated

# 粘贴图片

$ Ctrl+V 粘贴截图

[Image #1] 图片已缓存，发送时自动转录

# machine events

$ bash-agent --output-format stream-json "run tests"

{"type":"tool_result","session_id":"...","turn":12}

13 内置工具覆盖文件、搜索、执行、Web 和子 Agent

99%+ DeepSeek 长会话实测缓存命中率

1 log 所有模式统一写入 events.jsonl，stream-json 可同步输出

同一展示 直接执行、replay、不同语言版本走同层 display 语义

核心设计

不是 demo 脚本，而是一套可移植的 Agent 架构。

页面新增的信息集中在架构一致性、事件持久化和机器可消费输出上，这些是 bash-agent 和普通 CLI wrapper 最大的差别。

会话

长会话可恢复

按项目保存会话、turn、缓存统计和事件流。中断、compact、continue、replay 都围绕同一份 session 状态工作。

展示

展示层单独排队

Human 输出由 display queue 消费，stream-json 模式直接面向事件，不再把展示格式和事件格式混在一起。

工具

工具协议一致

Bash、C、Go、Rust 共用工具定义和调用语义，上层客户端不需要为不同运行时写多套解析逻辑。

缓存

缓存感知压缩

长 session 下优先保持 prompt/cache 边界稳定，降低重复输入成本，也让统计数据在版本切换后仍可兼容读取。

子 Agent

并行任务模型

支持 fork 上下文、后台运行、等待结果和隔离失败，适合把探索、验证、实现拆成并行工作流。

权限

Bash 工具权限模式

Bash 权限模型把命令分类到 system、external、network、workspace 四个 scope，并使用类似 Linux rwx 的 read、write、execute 三种权限位；四个运行时共用同一套分类和报错语义。

缓存性能实测

稳定前缀带来的缓存收益是可以量化的。

下面是 2026 年 5 月基于 DeepSeek API 长会话使用数据的缓存命中趋势。它不是对所有模型的承诺，而是展示 cache-aware session、prompt 和 compact 设计在真实使用中的效果。

总输入 Tokens 723,933,000

总输出 Tokens 2,504,956

平均缓存命中率 99.15%

观测天数 11 天

2026-05-06 96.70%

122K

2026-05-07 99.05%

216K

2026-05-08 99.88%

13K

2026-05-09 98.77%

36K

2026-05-15 99.37%

197K

2026-05-16 98.31%

362K

2026-05-17 99.45%

412K

2026-05-18 99.74%

240K

2026-05-19 99.78%

173K

2026-05-21 99.49%

359K

2026-05-22 98.77%

375K

注：数据来自 DeepSeek API 长会话使用记录；不同 provider、模型、任务形态和缓存策略会产生不同结果。

运行时一致性

四个版本，一套抽象层级。

Bash 是规格源头，C、Go、Rust 保持对应的链路层次。不同语言可以传结构体，不需要强行复制 Bash 的文件描述符限制。

Bash

规格源头

最小依赖、最容易审计，适合作为行为基准。

./src/agent.sh -i

C

原生

原生二进制，保留 display queue 和 replay 展示一致性。

./dist/cagent -i

Go

可移植

结构化 chain 层传递事件和展示消息，便于集成。

./dist/goagent -i

Rust

异步

异步执行和强类型状态管理，保持同层队列边界。

./dist/rustagent -i

事件管线

events.jsonl 是事实来源，display 只是消费者。

这也解释了为什么 stream-json 更适合抽象在 event append 层：同一个事件可以同时写入 session 文件，并在机器模式下输出到 stdout。

Agent 主循环 模型响应、工具调用、tool result 和 assistant message 都生成结构化事件。

事件追加 所有模式写入 events.jsonl；stream-json 模式在这里同步输出。

展示队列 Human 模式才进入展示队列，避免 JSON 输出夹杂提示符和格式化文本。

回放回放读取同一份事件，并复用相同 display 函数展示 tool 和消息。

统计兼容读取旧字段，写入时自然落到标准格式，避免单独 repair 文件。

快速开始

一分钟启动，可以选脚本版或原生版。

macOS 推荐 Homebrew；Arch Linux 保留 AUR 安装；只想验证 Bash 版时也可以直接下载单文件脚本。

Homebrew

# install all runtimes
brew install lloydzhou/tap/bash-agent

export DEEPSEEK_API_KEY="sk-..."
bash-agent "hello"

单文件脚本

curl -fsSL \
  https://github.com/lloydzhou/bash-agent/releases/latest/download/agent.sh \
  -o ~/.local/bin/bash-agent

chmod +x ~/.local/bin/bash-agent

Arch Linux (AUR)

# yay
yay -S bash-agent

# paru
paru -S bash-agent

OpenAI 兼容端点

OPENAI_BASE_URL=http://localhost:11434/v1 \
bash-agent -p openai -m llama3 "review this repo"

bash-agent --output-format stream-json "run tests"

内置工具

编码工作流需要的工具内置好了。

文件读写、搜索、Shell、Web、计划和子 Agent 都通过统一 tool schema 暴露。

文件读写与精确编辑

读取带行号的文件内容，写入新文件，并用精确字符串替换完成可审计修改。

Read Write Edit

搜索与定位

用 glob 和 ripgrep 快速定位上下文、文件和匹配片段，为后续编辑、测试和重构提供精确入口。

Glob Grep

受控 Bash 执行

执行测试、构建和诊断命令；Shell 权限按类似 Linux 文件权限的 rwx 位受控，并区分 system、external、network、workspace 四个 scope。

Bash

计划、待办与技能

把复杂任务拆成可跟踪步骤，锁定计划，并按需加载项目或用户定义的技能说明。

TodoWrite PlanConfirm PlanClear Skill

Web 查询与内容抓取

需要当前信息时搜索网页，或直接抓取 URL 内容并以结构化结果交给模型处理。

WebSearch WebFetch

并行子 Agent

把独立调查或验证任务交给子会话并行执行，结果回注主对话继续推理。

SubAgent