# 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，自带 `/ralph-loop`（复制任务循环）与 `/workflow`（YAML DAG 执行器）
- **自动上下文压缩**：接近上限时把旧对话压成摘要，保留系统提示 + 摘要 + 最近几条
- **多 session + 归档**：同一工作目录多个并行会话，`/new` 归档、`/restore` 恢复
- **可编程子进程**：`-p --output-format json` 输出一行结构化结局契约，方便被宿主程序 spawn 调度
- **三种运行形态**：源码跑（dev）/ npm 全局安装 / **bun --compile 绿色单文件夹**（免安装，可装 U 盘）

---

## 快速开始

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

```bash
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 跑发布产物（见「三种运行形态」）。

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

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

## 配置

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

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

必需三项 + 可选项：

```env
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

```bash
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`、`/ralph-loop` 是**插件命令**（见下）。

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

```bash
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）：

```json
{ "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/` 一行不改）：
  - **`/ralph-loop`**（ralph-wiggum）—— Karpathy 式复制任务循环，自带 PLAN/BUILD/VERIFY/HEAL 状态机 + 验证门
  - **`/workflow` · `/workflows`**（workflow-runner）—— YAML DAG 执行器，9 种 step（tool/llm/skill/assert/branch/loop/pause/parallel/vote）
- **可视化编辑器**：`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](./GREEN-BUILD.md)**。

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

---

## 开发

```bash
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](./CLAUDE.md)**。

## 目录结构

```
minimal-agent/
├─ src/            # 主程序（loop / tools / llm / ui / plugins / config …）
├─ skills/         # 内置 skill（每个一个 SKILL.md）
├─ plugins/        # 内置插件（ralph-wiggum / 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](./LICENSE) © 2026 billsoft。
允许非商业用途的使用、修改与分发；商业用途请联系作者。
