minimal-agent

一个最小化但功能完整的 AI 编程助手 —— Bun + React + TypeScript + Ink TUI 构建， OpenAI 兼容、多 provider，11 个内置工具 + Skills + 插件 + Workflow DSL + 自动上下文压缩。 为学习与教学而生：代码量克制、注释充分，把一个 agent「从输入到工具循环到落盘」讲透。

v0.5.1 · Runtime: Bun（主）/ Node ≥ 20 · License: PolyForm Noncommercial 1.0.0

这是什么

一个能在终端里跟你对话、并真正动手改代码的 AI agent。核心是一个 AsyncGenerator 主循环 （src/loop.ts）：

用户输入 → 调 LLM → LLM 要调工具就执行 → 结果喂回去 → 继续调 LLM → … → 不再调工具 → 输出最终回答

每轮 yield 一个事件给 UI 实时刷新。上下文快撑爆时自动压缩成结构化摘要。麻雀虽小， 工具系统、Skills、插件、Workflow、多 session、自动压缩、可编程子进程契约一应俱全。

特性

• 11 个内置工具：Read / Write / Edit / MultiEdit / Glob / Grep / WebSearch / WebFetch / WebBrowser / Bash / AskUserQuestion（向用户提结构化选择题，动态工作流交互底座）
• OpenAI 兼容：Message 形状对齐 Chat Completions，一套代码接 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot…
• Skills 系统：放一个 SKILL.md 就能扩展能力，运行时实时扫描注入 prompt，改文件即生效
• 插件系统：plugins/<id>/ drop-in，自带 /workflow（YAML 工作流引擎，支持 while 循环 + 验证门 + fresh_context）
• 自动上下文压缩：接近上限时把旧对话压成摘要，保留系统提示 + 摘要 + 最近几条
• 多 session + 归档：同一工作目录多个并行会话，/new 归档、/restore 恢复
• 可编程子进程：-p --output-format json 输出一行结构化结局契约，方便被宿主程序 spawn 调度
• 三种运行形态：源码跑（dev）/ npm 全局安装 / bun --compile 绿色单文件夹（免安装，可装 U 盘）

快速开始

方式一：源码运行（推荐学习用）

git clone https://github.com/billsoft/kakadeai.git
cd kakadeai/minimal-agent
bun install
cp .env.example .env        # 填入你的 API key（见下）
bun run start               # 启动 TUI

没装 Bun？见 https://bun.sh 。也可在缺 Bun 时用 Node 跑发布产物（见「三种运行形态」）。

方式二：全局安装后随处可用

npm install -g minimal-agent
minimal-agent                # 首次运行进入配置向导

配置

两种方式任选其一（环境变量优先级高于配置文件）：

1. .env 文件（源码模式，Bun 自动加载）—— 复制 .env.example 改值。
2. 配置向导 —— 首次运行 minimal-agent（TUI）会引导你填，写到 ~/.minimal-agent/config.json。

必需三项 + 可选项：

MINIMAL_AGENT_BASE_URL=https://api.minimax.chat/v1   # 必需：API 地址
MINIMAL_AGENT_API_KEY=your-api-key                   # 必需：API key
MINIMAL_AGENT_MODEL=MiniMax-M2.7                     # 必需：模型名
MINIMAL_AGENT_PROVIDER=minimax                       # 可选：友好名，默认 "env"
MINIMAL_AGENT_CONTEXT_WINDOW=204800                  # 可选：上下文窗口，默认 128000
TAVILY_API_KEY=                                      # 可选：WebSearch 工具用（https://tavily.com）

.env.example 里附了 MiniMax / 火山 ARK / DeepSeek / OpenAI / Moonshot 五套现成模板，注释切换即可。

使用

交互式 TUI

bun run start        # 或全局安装后直接 minimal-agent

布局自上而下：消息列表（scrollback）→ 本轮过程区（流式思维链/工具进度）→ 输入框 → 状态栏。 ESC / Ctrl+C 中断当前任务，Alt+Enter 输入框换行。

内置 slash 命令（不走 LLM，UI 层直接拦截）：

| 命令 | 作用 | |---|---| | /new（/clear） | 归档当前对话 → 清空 → 用最新 skills 重建 system prompt | | /compact | 手动压缩当前对话 | | /session <name> · /sessions | 切换 / 列出同目录下的并行会话 | | /list-archive · /restore <id> | 列出 / 恢复归档对话 | | /show <id> | 展开某次工具调用的完整输出（列表默认折叠到 3 行） | | /exit（/quit） | 退出 |

/init、/config 等是 LLM 驱动的 skill；/workflow、/workflows 是插件激活入口（见下）。

非交互模式（-p）—— 脚本 / CI / 被宿主程序调用

minimal-agent -p "帮我写一个 hello world"
echo "解释这段代码" | minimal-agent -p
minimal-agent -p "处理资料" -d /tmp/job-123              # -d 隔离工作目录
minimal-agent -p --output-format json "做点事"           # 一行结构化结局契约

| 选项 | 说明 | |---|---| | -p / --print | 非交互单次问答，输出后退出 | | -v / --verbose | stderr 显示工具调用、压缩等过程 | | -d <dir> / --cwd <dir> | 指定工作目录（不存在自动创建），隔离文件视图与会话 | | --output-format <text\|json> | text（默认，纯文本答案）/ json（一行结局契约） | | --max-turns <n> | 最大工具循环轮数（防失控，默认 50） | | -V / --version · -h / --help | 版本 / 帮助 |

--output-format json 结局契约（供宿主程序可靠 spawn）：

{ "ok": true, "result": "...", "is_error": false,
  "stop_reason": "end_turn", "num_turns": 3, "error": null }

ok = (stop_reason === 'end_turn')；stop_reason ∈ end_turn | max_turns | error | interrupted | config_error。

⚠️ ok=true 只代表「正常跑完未报错」，不代表任务目标达成——宿主应额外校验 result / 产物文件。

工具

| 工具 | 底层 | 说明 | |---|---|---| | Read | node:fs | 支持 offset/limit、二进制嗅探 | | Write | node:fs | 整体写入；覆盖前需先 Read | | Edit | node:fs | old_string 必须唯一 | | MultiEdit | node:fs | 单文件一次多处替换 | | Glob | fast-glob | 文件名 pattern | | Grep | 自带 ripgrep | 内容搜索，自带 6 平台二进制，开箱即用 | | WebSearch | Tavily API | 需 TAVILY_API_KEY | | WebFetch | fetch + turndown | HTML → Markdown，LRU 缓存 | | WebBrowser | playwright-core（可选） | 缺依赖时自动降级 WebFetch | | Bash | child_process | 黑名单 + 超时双保险 |

工具失败不抛异常——把 error 写进结果喂回 LLM 让它自己重试。

Skills · 插件 · Workflow

• Skills：每个 skills/<name>/SKILL.md（带 frontmatter）。运行时实时扫描注入 prompt，prompt 体按需懒加载。 cwd 优先、包内 fallback，用户可在自己项目里覆盖或新增。内置 20+ 个（/init、/config、文档生成、设计等）。
• 插件（plugins/<id>/，drop-in，src/ 一行不改）：
  • /workflow · /workflows（workflow-runner）—— YAML 工作流引擎，10 种 step（tool/llm/skill/assert/agent/branch/loop/break/pause/parallel/vote），支持 while 循环 + fresh_context + 验证门。内置 ralph-loop 等工作流定义
• 可视化编辑器：editor/ 子项目（Bun + Vite + React Flow）拖拽编排 workflow YAML（不属于 npm 发布物）。

三种运行形态

| 形态 | 怎么跑 | 适合 | |---|---|---| | 源码 dev | bun run dev（Bun 直接吃 .ts，watch 热重载） | 学习、改源码 | | npm 安装 | npm i -g minimal-agent → minimal-agent（Node 吃 tsc 编译的 .js） | 日常使用 | | 绿色版 | bun run compile:green → 单文件夹（内嵌运行时，免装 Node/Bun） | 免安装分发 / 装 U 盘 |

绿色版把运行时 + 全部依赖 + 工具执行器编译进单个可执行文件，连同 vendor/ripgrep、skills、 workflows、插件一起组装成「拷到任意机器即插即用」的文件夹；支持把 config.json 预置在目录里做到 零配置开箱即用。三平台（Windows / macOS / Linux）各一份。详见 GREEN-BUILD.md。

bun run compile:green                 # 三主平台：win-x64 / mac-arm64 / linux-x64
bun run compile:green:host            # 仅当前平台
bun run compile:green -- --config 你的config.json   # 编译时烧录预配置

开发

bun install            # 安装依赖
bun run start          # 运行（= bun run src/main.tsx）
bun run dev            # watch 热重载
bun test               # 跑所有测试
bun run typecheck      # tsc --noEmit
bun run build          # tsc --build → src/*.js + plugins/*.js（npm 发布用）
bun run clean          # 删除原地编译产物

格式/检查用 Biome（2 空格缩进、单引号、80 列）。模块解析 NodeNext：源码 import 统一写 .js 后缀， dev 下 Bun 透明回退到 .ts 兄弟，发布前 tsc --build 原地产出 .js。

架构速览

| 模块 | 职责 | |---|---| | src/loop.ts | runQuery() 主循环（AsyncGenerator）—— 系统的「心脏」 | | src/llm/client.ts | OpenAI 兼容流式客户端（text / tool_call / reasoning 三路） | | src/types.ts | 对齐 Chat Completions 的 Message / ToolCall / 事件类型 | | src/tools/ | 11 个工具 + executeTool() 参数防线（JSON.parse → Zod → call） | | src/context/compact.ts | 自动上下文压缩 | | src/prompts/ | system prompt 组装 + Skills 实时扫描注入 | | src/plugins/ | 插件框架（discovery / 命令路由 / hook 引擎 / transcript） | | src/ui/ | Ink TUI（MessageList / LiveArea / InputBox / StatusLine） | | src/config.ts · src/config/ | 分层 provider 配置（env → 配置文件） |

给 Claude Code / 维护者的深入说明见 CLAUDE.md。

目录结构

minimal-agent/
├─ src/            # 主程序（loop / tools / llm / ui / plugins / config …）
├─ skills/         # 内置 skill（每个一个 SKILL.md）
├─ plugins/        # 内置插件（workflow-runner）
├─ workflows/      # 内置 workflow（YAML）
├─ vendor/ripgrep/ # Grep 自带的 6 平台 ripgrep 二进制
├─ scripts/        # 构建脚本（含绿色版 build-green.ts）
├─ editor/         # workflow 可视化编辑器（独立子项目）
├─ test/           # 测试
├─ GREEN-BUILD.md  # 绿色版/U 盘分发指南
└─ CLAUDE.md       # 架构与开发指南

License

PolyForm Noncommercial License 1.0.0 © 2026 billsoft。 允许非商业用途的使用、修改与分发；商业用途请联系作者。