minimal-agent 0.1.0

package/LICENSE

@@ -0,0 +1,148 @@
+Copyright (c) 2026 billsoft
+
+Licensed under the PolyForm Noncommercial License 1.0.0.
+
+PolyForm Noncommercial License 1.0.0
+====================================
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Acceptance
+----------
+
+In order to get any license under these terms, you must agree to them as
+both strict obligations and conditions to all your licenses.
+
+Copyright License
+-----------------
+
+The licensor grants you a copyright license for the software to do
+everything you might do with the software that would otherwise infringe
+the licensor's copyright in it for any permitted purpose. However, you
+may only distribute the software according to Distribution License and
+make changes or new works based on the software according to Changes
+and New Works License.
+
+Distribution License
+--------------------
+
+The licensor grants you an additional copyright license to distribute
+copies of the software. Your license to distribute covers distributing
+the software with changes and new works permitted by Changes and New
+Works License.
+
+Notices
+-------
+
+You must ensure that anyone who gets a copy of any part of the software
+from you also gets a copy of these terms or the URL for them above, as
+well as copies of any plain-text lines beginning with `Required Notice:`
+that the licensor provided with the software. For example:
+
+> Required Notice: Copyright (c) 2026 billsoft
+
+Changes and New Works License
+-----------------------------
+
+The licensor grants you an additional copyright license to make changes
+and new works based on the software for any permitted purpose.
+
+Patent License
+--------------
+
+The licensor grants you a patent license for the software that covers
+patent claims the licensor can license, or becomes able to license, that
+you would infringe by using the software.
+
+Noncommercial Purposes
+----------------------
+
+Any noncommercial purpose is a permitted purpose.
+
+Personal Uses
+-------------
+
+Personal use for research, experiment, and testing for the benefit of
+public knowledge, personal study, private entertainment, hobby projects,
+amateur pursuits, or religious observance, without any anticipated
+commercial application, is use for a permitted purpose.
+
+Noncommercial Organizations
+---------------------------
+
+Use by any charitable organization, educational institution, public
+research organization, public safety or health organization,
+environmental protection organization, or government institution is use
+for a permitted purpose regardless of the source of funding or
+obligations resulting from the funding.
+
+Fair Use
+--------
+
+You may have "fair use" rights for the software under the law. These
+terms do not limit them.
+
+No Other Rights
+---------------
+
+These terms do not allow you to sublicense or transfer any of your
+licenses to anyone else, or prevent the licensor from granting licenses
+to anyone else. These terms do not imply any other licenses.
+
+Patent Defense
+--------------
+
+If you make any written claim that the software infringes or contributes
+to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such
+a claim, your patent license ends immediately for work on behalf of
+your company.
+
+Violations
+----------
+
+The first time you are notified in writing that you have violated any
+of these terms, or done anything with the software not covered by your
+licenses, your licenses can nonetheless continue if you come into full
+compliance with these terms, and take practical steps to correct past
+violations, within 32 days of receiving notice. Otherwise, all your
+licenses end immediately.
+
+No Liability
+------------
+
+***As far as the law allows, the software comes as is, without any
+warranty or condition, and the licensor will not be liable to you for
+any damages arising out of these terms or the use or nature of the
+software, under any kind of legal claim.***
+
+Definitions
+-----------
+
+The **licensor** is the individual or entity offering these terms, and
+the **software** is the software the licensor makes available under
+these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other
+kind of organization that you work for, plus all organizations that
+have control over, are under the control of, or are under common
+control with that organization. **Control** means ownership of
+substantially all the assets of an entity, or the power to direct its
+management and policies by vote, contract, or otherwise. Control can be
+direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software
+under these terms.
+
+**Use** means anything you do with the software requiring one of your
+licenses.
+
+---
+
+Required Notice: Copyright (c) 2026 billsoft
+
+`vendor/ripgrep/` 内的二进制为上游 ripgrep 项目的原始 MIT / Unlicense
+双重许可，不受本项目 PolyForm Noncommercial License 约束。详见
+`vendor/ripgrep/COPYING`。

package/README.md

@@ -0,0 +1,287 @@
+# minimal-agent
+
+> 最小化的 AI 编程助手 —— 单对话 · 9 个内置工具 · 自动压缩 · OpenAI 兼容协议 · Ink TUI
+
+一个用于**学习和教学**的 Agent 项目，从 [kakadeai](../) 主仓库的 Claude Code 源码中抽取并简化而来，把"一个能调工具、能自动压缩上下文、能流式输出的 agent"在 ~3000 行 TypeScript 内讲清楚。
+
+---
+
+## 特性
+
+| 模块 | 说明 |
+|---|---|
+| 🧠 主循环 | `runQuery` 用 AsyncGenerator 把"调 LLM → 跑工具 → 喂回去"串成一条流 |
+| 🔧 内置工具 | Read / Write / Edit / Glob / Grep / Bash / WebSearch / WebFetch / WebBrowser |
+| 📦 自动压缩 | 接近 context window 时自动摘要历史（auto / micro / reactive 三层） |
+| 💾 单上下文 | `~/.minimal-agent/last-context.json` 自动保存/恢复，无 session 概念 |
+| 🎨 双模式 | Ink TUI 交互模式 + `-p` 非交互 CLI 模式（管道友好） |
+| 🌐 多 provider | 走 OpenAI Chat Completions 协议，配 .env 即可切换 MiniMax / DeepSeek / Kimi / OpenAI |
+| 🧰 Skills 系统 | 扫描 `skills/<name>/SKILL.md` frontmatter，按需懒加载完整 prompt |
+
+---
+
+## 系统要求
+
+- **Bun ≥ 1.1**（推荐，主运行时）；Node.js ≥ 20 需要走 build 流程，见末尾的[发布到 npm](#发布到-npm未来) 章节
+- 一个 OpenAI 兼容的 LLM API（MiniMax / OpenAI / DeepSeek / Kimi / 自建 vLLM 均可）
+- *可选*：[Tavily](https://tavily.com) API key（开启 WebSearch）
+- *可选*：`playwright-core` + chromium（开启 WebBrowser；不装会自动降级到 WebFetch）
+- *无需安装 ripgrep* —— 项目自带 `vendor/ripgrep/` 6 个平台二进制（arm64/x64 × win32/darwin/linux）
+
+---
+
+## 快速开始
+
+支持两种配置方式，**任选其一**即可：
+
+### 方式 A：手写 .env（适合开发者 / `-p` 非交互模式）
+
+```bash
+# 1. 安装依赖
+bun install
+
+# 2. 配置 .env（参考 .env.example）
+cp .env.example .env
+# 编辑 .env 填入 BASE_URL / API_KEY / MODEL
+
+# 3. 启动 TUI
+bun run start
+```
+
+### 方式 B：首次启动配置向导（适合零配置上手）
+
+```bash
+bun install
+bun run start    # 没检测到任何配置 → 自动弹 Ink 向导
+```
+
+向导步骤：选 provider 预设（MiniMax / DeepSeek / OpenAI / Kimi / 自定义）→ 填 baseURL → 填 API key（掩码显示）→ 选 model → 自动做一次连通性测试 → 通过后写入 `~/.minimal-agent/config.json` 并直接进入对话界面。
+
+> 测试不通过或中途 ESC 退出 → **不写文件** → 下次启动继续走向导，直到成功为止。
+
+### 运行示例
+
+```bash
+bun run src/main.tsx -p "帮我写个 hello world"   # 一次性问答
+echo "解释这段代码" | bun run src/main.tsx -p     # 管道输入
+```
+
+### 配置优先级
+
+```
+process.env  >  ~/.minimal-agent/config.json  >  弹向导
+```
+
+env 永远盖过 JSON，**逐字段**生效（可以只用 env 临时覆盖单个字段做调试）。`-p` 模式不会弹向导（没 TTY），缺配置直接 stderr 报错退出。
+
+### .env 字段
+
+```env
+# 必需
+MINIMAL_AGENT_BASE_URL=https://api.minimax.chat/v1
+MINIMAL_AGENT_API_KEY=your-api-key
+MINIMAL_AGENT_MODEL=MiniMax-M2.7
+
+# 可选
+MINIMAL_AGENT_PROVIDER=minimax           # 仅作显示用，默认 "env"
+MINIMAL_AGENT_CONTEXT_WINDOW=204800      # 模型上下文窗口，默认 128000
+TAVILY_API_KEY=                          # 启用 WebSearch
+```
+
+### 重新配置
+
+在 TUI 内直接输入 `/config`（不带任何其他内容），LLM 会按 `skills/config/SKILL.md` 流程逐项询问后用 Write 工具更新 `~/.minimal-agent/config.json`，提示重启生效。
+
+> `/config` 是 **LLM 驱动的 skill**（同 `/init`），不是硬编码命令（不同于 `/new` / `/compact`）—— 必须**单独输入 `/config`**，带其他内容（如 `/config 帮我看看`）不会触发。
+
+---
+
+## 命令行参数
+
+```
+minimal-agent [选项] [提示...]
+echo "提示" | minimal-agent [选项]
+
+选项:
+  -p, --print        非交互模式，问答一次后退出
+  -v, --verbose      显示工具调用 / 压缩详情
+  -h, --help         帮助
+  -V, --version      版本号
+```
+
+TUI 内部支持：
+
+| 输入 | 效果 |
+|---|---|
+| `/new` | 清空历史，重建 system prompt（带最新 skills + 项目指令） |
+| `/compact` | 手动压缩当前对话 |
+| `/config` | 重新配置 LLM provider（LLM 驱动 skill，单独输入才触发） |
+| `Alt+Enter` | 输入框换行（教学/多行 prompt 友好） |
+| `ESC` / `Ctrl+C` | 中断当前任务 |
+
+---
+
+## 内置工具
+
+| 名称 | 用途 | 实现 |
+|---|---|---|
+| `Read` | 读文件（支持 offset / limit / 二进制嗅探） | `node:fs/promises` |
+| `Write` | 整体写文件（覆盖前要先 Read） | `node:fs/promises` |
+| `Edit` | 字符串精确替换（old_string 必须唯一） | `node:fs/promises` |
+| `Glob` | 文件名模式匹配 | `fast-glob` |
+| `Grep` | 文件内容搜索 | spawn vendor 内置 ripgrep |
+| `Bash` | 终端命令执行（黑名单 + 超时双保险） | `node:child_process` |
+| `WebSearch` | Web 搜索（自动注入当前日期） | Tavily API |
+| `WebFetch` | 抓网页 → HTML→Markdown（LRU 缓存） | `fetch` + `turndown` |
+| `WebBrowser` | 浏览器交互（点击/填表单/截图/JS 渲染） | playwright-core（**可选依赖**） |
+
+工具入口：`src/tools/index.ts` 的 `ALL_TOOLS` 数组和 `executeTool()` 函数。
+
+---
+
+## 项目结构
+
+```
+minimal-agent/
+├── src/
+│   ├── main.tsx                    # 入口：CLI 参数解析 + 模式分发
+│   ├── loop.ts                     # Agent 主循环（runQuery）
+│   ├── config.ts                   # .env 加载
+│   ├── types.ts                    # 核心类型（Message / Tool / LoopEvent）
+│   ├── cli/print.ts                # -p 非交互模式
+│   ├── llm/client.ts               # OpenAI 兼容流式客户端
+│   ├── context/                    # 压缩 / 持久化 / token 计数
+│   │   ├── compact.ts              # auto + force 压缩
+│   │   ├── reactiveCompact.ts      # 上下文撑爆时的自救
+│   │   ├── microCompactLite.ts     # 工具回填 inline 压缩
+│   │   └── persistContext.ts       # ~/.minimal-agent/last-context.json
+│   ├── prompts/                    # system prompt 拼装
+│   │   ├── system.ts               # 主 prompt + 项目指令注入
+│   │   ├── projectInstructions.ts  # 项目根 minimal-agent.md 加载
+│   │   └── skillList.ts            # 扫描 skills/ 生成 skill 列表
+│   ├── tools/                      # 9 个内置工具（见上表）
+│   └── ui/                         # Ink TUI 组件
+├── skills/                         # Skill 库（每个子目录一个 SKILL.md）
+├── vendor/ripgrep/                 # 自带的 ripgrep 二进制（6 个平台）
+├── test/                           # bun test 用例
+├── examples/                       # Ink 教学示例
+└── minimal-agent.md                # 项目指令（类似 CLAUDE.md，会被自动注入 system prompt）
+```
+
+---
+
+## 工作原理（一句话版）
+
+```
+用户输入
+  │
+  ▼
+runQuery (loop.ts)
+  │
+  ├── autoCompactIfNeeded   # 接近上限就压缩
+  ├── chat(LLM)             # 流式 token + tool_calls
+  ├── yield {text, ...}     # → UI 显示
+  │
+  ├── if 没工具 → return    # 任务完成
+  │
+  ├── for each tool_call:
+  │     executeTool         # zod 校验 → tool.call(args)
+  │     append tool result  # 写回 history
+  │
+  └── continue              # 下一轮
+```
+
+详见 `src/loop.ts` 的注释。
+
+---
+
+## 开发命令
+
+```bash
+bun run start         # 跑 TUI
+bun run dev           # 热重载
+bun test              # 跑全部测试（test/*）
+bun test test/llm.live.test.ts  # 跑单个测试文件
+tsc --noEmit          # 类型检查
+```
+
+---
+
+## 与 [kakadeai](../) 主项目的关系
+
+minimal-agent 是 Claude Code 源码的**教学版**：
+
+| 维度 | kakadeai/Claude Code | minimal-agent |
+|---|---|---|
+| 代码量 | 数十万行 | ~3000 行 |
+| 主循环 | QueryEngine + 状态机 | 单层 while + AsyncGenerator |
+| Tool 数 | 60+（含 MCP / Agent / Notebook 等） | 9 个内置 |
+| Skill 加载 | `registerBundledSkill()` 注册 | 扫描目录 + frontmatter 解析 |
+| Provider | Anthropic SDK | OpenAI Chat Completions（多家兼容） |
+| UI | 完整 Ink 框架 + 主题系统 | 基础 Ink 组件 |
+
+设计目标是**砍掉一切非必要的抽象**，把"AI agent 是什么"暴露在你眼前。
+
+---
+
+## 故障排查
+
+| 现象 | 原因 / 处理 |
+|---|---|
+| `-p` 模式报 `缺少必需的环境变量` | `-p` 不弹向导。先用 `bun run start` 走向导，或手动写 `.env` |
+| TUI 启动就弹向导，但我已经写了 .env | 检查 .env 是否在项目根（`bun run` 当前目录），三项变量名拼写无误 |
+| 向导测试卡 `HTTP 401` / `HTTP 404` | 401 = API key 错；404 = baseURL 没拼 `/v1` 或 model id 不对 |
+| 改完 `~/.minimal-agent/config.json` 没生效 | 当前进程仍持有旧配置；Ctrl+C 退出后重新 `bun run start` |
+| `rg: command not found` | 不该出现——项目自带 ripgrep；若出现说明 vendor 目录未随项目复制 |
+| `WebBrowser 报"无法启动浏览器"` | 需要 `npm install playwright-core && npx playwright install chromium`；或改用 WebFetch |
+| 历史"被吃掉"了 | 上次进程崩溃前未保存；`~/.minimal-agent/last-context.json` 是最后写入的一次 |
+| 模型回复说"我没法访问外部 API" | 检查 `MINIMAL_AGENT_BASE_URL` 是否拼了 `/v1`，model id 是否对 |
+
+---
+
+## 发布到 npm（未来）
+
+**当前状态：不能直接 `npm install -g minimal-agent`** —— `package.json` 里 `"private": true`，也没有 `bin` 字段和构建产物。
+
+如果要发布到 npm 让 Node.js 用户也能用，至少要做：
+
+1. **改 `package.json`**
+   - 去掉 `"private": true`
+   - 加 `"bin": { "minimal-agent": "dist/main.js" }`
+   - 加 `"files": ["dist", "vendor", "skills"]`（控制 npm tarball 内容）
+   - 加 `"engines": { "node": ">=20" }`
+2. **加构建步骤**：用 tsup / esbuild 把 `src/main.tsx` bundle 成单文件 CJS+ESM，输出到 `dist/main.js`
+3. **shebang**：构建产物首行加 `#!/usr/bin/env node`，发布前 `chmod +x`
+4. **`.env` 不打包**：在 `.npmignore` 里排除 `.env*`、`vendor/ripgrep/test/`，依赖**配置向导**让用户首次跑 `npx minimal-agent` 时填配置（这正是本项目 Mode B 的设计目的）
+5. **vendor ripgrep**：6 个平台二进制（~30MB）会进 tarball；如想瘦身可拆成 `optionalDependencies` 按平台下载
+6. **首发流程**：`npm whoami` → `npm publish --dry-run` 验证 tarball → `npm publish`
+
+发布后用户体验：
+
+```bash
+npm install -g minimal-agent
+minimal-agent              # 没配置 → 弹向导 → 测试通过 → 直接进 TUI
+minimal-agent -p "..."     # 配置完成后可直接 -p
+```
+
+**本项目尚未做这步**，本仓库定位为学习/教学版，主要面向 `bun run start` / `bun run dev` 本地运行的用户。
+
+---
+
+## License
+
+本项目使用 **PolyForm Noncommercial License 1.0.0**（详见根目录 `LICENSE` 文件）。
+
+**允许**：
+- 个人学习、教学、研究、非商业实验用途
+- 修改源代码、本地构建、自托管运行
+- 在非商业项目中引用 / fork
+- 慈善机构、教育机构、公共研究组织等非营利组织使用
+
+**禁止**：
+- 任何形式的商业使用（包括但不限于：销售本软件、用于公司内部生产环境、作为商业产品的组件、提供付费服务）
+- 未经授权的再分发（必须保留 LICENSE 与版权声明）
+
+如需商业授权，请联系作者另行洽谈。
+
+`vendor/ripgrep/` 内的二进制为上游 ripgrep 项目的 MIT / Unlicense 双重许可，**不受**本项目 PolyForm Noncommercial License 约束。