min-agent 0.1.4 → 0.1.5

package/README.md

@@ -1,85 +1,144 @@
 # min-agent
 
-轻量级 AI Agent，支持工具调用（读写文件、Shell、搜索）、MCP 与 Skill。  
-兼容 OpenAI 风格 API（OpenAI、Ollama、vLLM、MiniMax、DeepSeek 等）。
+Minimal yet powerful AI coding agent for the terminal. Supports any OpenAI-compatible API, MCP servers, skills, memory, and multi-agent parallel execution.
 
-## 安装
-
-需要 **Node.js 20+**。入口为 **`bin/min-agent.js`**（含 `#!/usr/bin/env node`），由 npm/npx 生成 `.cmd` 时用 **`node` 执行**，避免 Windows 把无 shebang 的 `dist/cli.js` 当成「用默认应用打开」。发布包内含 **`tsc` 编译后的 `dist/`**（多文件 ESM），安装时会随 **`dependencies`** 安装 `ai`、`glob` 等；npm 会与同级包 **dedupe**。
+## Install
 
 ```bash
 npm install -g min-agent
-# 或
-npx -y min-agent --help
 ```
 
-## 快速开始
+## Quick Start
 
 ```bash
-# 1) 交互式配置 provider / api key / 默认模型
+# 1. Configure your LLM provider
 min-agent setup
 
-# 2) 单轮问答
-min-agent chat "hello"
-min-agent chat "read package.json and tell me the version"
-min-agent chat "帮我搜索一下最新的 AI 新闻"
+# 2. Chat mode (general assistant)
+min-agent chat "what files are in this directory?"
+
+# 3. Code mode (project-aware AI coding)
+min-agent code
+```
+
+---
+
+## Commands
+
+### Chat
+
+```bash
+min-agent chat <message>          # Single-shot message
+min-agent chat                    # Interactive multi-turn session
+min-agent chat --resume <id>      # Resume a previous session
+min-agent chat -m <model> "msg"   # Use a specific model
+min-agent chat -i img.png "what's this?"  # Attach image
+```
+
+### Code (AI Coding Mode)
 
-# 3) 进入多轮对话
-min-agent chat
+```bash
+min-agent code                    # Project-aware coding session
+min-agent code --resume <id>      # Resume coding session
 ```
 
-## 首次运行会自动初始化
+Code mode automatically:
+- Scans the project (language, framework, git status, structure)
+- Uses a coding-optimized system prompt
+- Includes the `explore` tool for deep codebase analysis
+- Follows project conventions (no comments, match existing style)
+
+### Configuration
 
-在当前项目目录自动确保以下结构存在：
+```bash
+min-agent setup                   # Interactive provider setup
+min-agent models                  # List available models
+min-agent rules                   # Show loaded instruction rules
+min-agent rules edit              # Edit global rules file
+```
 
-- `.min-agent/skills/`
-- `.min-agent/mcp.json`（默认 `{ "mcpServers": {} }`）
+### Memory
 
-用户全局技能目录 `~/.agents/skills/` 不会自动创建；若你自行创建并放入 `SKILL.md`，启动时会被扫描加载（见下文「Skill 安装」）。
+```bash
+min-agent memory                  # List all memories
+min-agent memory add "text"       # Add manually
+min-agent memory search "query"   # Search
+min-agent memory delete <n>       # Delete by number
+```
+
+The agent also saves memories automatically during conversations when you share preferences or important context.
+
+### Sessions
+
+```bash
+min-agent history                 # List saved sessions
+min-agent chat --resume <id>      # Resume a session
+```
 
-## CLI 命令
+Sessions are auto-saved when you exit interactive chat/code mode, with LLM-generated titles.
+
+### MCP (Model Context Protocol)
+
+```bash
+min-agent mcp add <name> <cmd...>                    # Add local stdio server
+min-agent mcp add <name> --url <url> [--token <t>]   # Add remote HTTP server
+min-agent mcp remove <name>                          # Remove server
+min-agent mcp list                                   # List servers
+min-agent mcp check                                  # Check connectivity
+```
+
+### Skills
+
+```bash
+min-agent skills list             # List available skills
+```
+
+### HTTP API
+
+```bash
+min-agent serve                   # Start HTTP server (default :8787)
+min-agent serve --port 3000       # Custom port
+```
+
+See [docs/API.md](docs/API.md) for full API reference.
+
+---
+
+## Interactive Commands
+
+In chat/code mode, use slash commands:
 
 | Command | Description |
 |---------|-------------|
-| `min-agent setup` | 交互配置 API URL、Key、默认模型 |
-| `min-agent chat <message>` | 单轮消息 |
-| `min-agent chat` | 多轮交互聊天 |
-| `min-agent chat -m <model> <message>` | 指定模型发送消息 |
-| `min-agent models` | 拉取并列出可用模型 |
-| `min-agent mcp add <name> <cmd...>` | 添加本地 MCP（stdio，默认先验证） |
-| `min-agent mcp add <name> --url <url> [--sse] [--token …]` | 添加远程 MCP（HTTP） |
-| `min-agent mcp remove <name>` | 删除 MCP 服务 |
-| `min-agent mcp list` | 列出 MCP 服务 |
-| `min-agent mcp check` | 检查所有 MCP 服务可用性 |
-| `min-agent skills list` | 列出已发现 skills |
-| `min-agent rules` | 查看已加载规则来源 |
-| `min-agent rules edit` | 编辑全局规则文件 |
-| `min-agent history` | 查看会话历史 |
-| `min-agent memory` | 查看记忆 |
-| `min-agent memory add <text>` | 新增记忆 |
-| `min-agent memory search <query>` | 检索记忆 |
-| `min-agent memory delete <index>` | 删除记忆 |
-
-## 交互聊天 Slash 命令（`min-agent chat` 内）
-
-| Slash Command | Description |
-|---------------|-------------|
-| `/clear` | 清空当前会话消息 |
-| `/compact` | 强制压缩上下文 |
-| `/model [name]` | 查看或设置默认模型 |
-| `/models` | 拉取并列出 provider 模型 |
-| `/memory [text]` | 查看记忆或保存记忆 |
-| `/skills` | 列出当前已发现 skills |
-| `/mcp` | 查看 MCP 服务与连接状态 |
-| `/tokens` | 显示上下文 token 估算 |
-| `/help` | 显示帮助 |
-| `/exit` | 退出聊天 |
-
-## 配置文件与加载规则
-
-### Provider 配置
-
-保存在 `~/.min-agent/config.json`：
+| `/clear` | Clear conversation history |
+| `/compact` | Force context compaction |
+| `/model [name]` | Show or change model |
+| `/memory [text]` | List or save memory |
+| `/tokens` | Show context window usage |
+| `/path` | Show working directory |
+| `/help` | Show all commands |
+| `/exit` | Exit session |
+
+**Ctrl+C** interrupts the current generation without exiting.
+
+---
+
+## Configuration
+
+All config lives in `~/.min-agent/`:
+
+```
+~/.min-agent/
+├── config.json              # Provider, model, instructions
+├── rules.md                 # Global rules (always injected)
+├── mcp.json                 # MCP server definitions
+├── memory.json              # Persistent memories
+├── models-cache.json        # Model list cache (fallback)
+├── context-window-cache.json # Context window cache
+└── sessions/                # Saved conversation sessions
+```
+
+### config.json
 
 ```json
 {
@@ -87,70 +146,121 @@ min-agent chat
     "type": "openai-compatible",
     "baseURL": "https://api.openai.com/v1",
     "apiKey": "sk-...",
-    "defaultModel": "gpt-4o"
-  }
+    "defaultModel": "gpt-4o",
+    "contextWindow": 128000
+  },
+  "instructions": [
+    "./docs/CODING_RULES.md",
+    "https://example.com/team-rules.md"
+  ]
 }
 ```
 
-说明：
+### Provider Types
 
-- `setup` 时根据填写信息自动拉取模型列表。
-- Ollama 支持填 `http://host:11434` 或 `http://host:11434/v1`，会自动兼容。
+| Type | Description |
+|------|-------------|
+| `openai-compatible` | Any OpenAI-compatible API (MiniMax, DeepSeek, vLLM, etc.) |
+| `openai` | OpenAI official |
+| `ollama` | Local Ollama (`http://localhost:11434/v1`) |
 
-### MCP 配置
+### Context Window Auto-Detection
 
-项目级配置：`.min-agent/mcp.json`
+The context window size is automatically detected from:
+1. `config.provider.contextWindow` (manual override)
+2. OpenRouter API (`context_length`)
+3. Ollama API (`/api/show`)
+4. vLLM API (`max_model_len`)
+5. [models.dev](https://models.dev) database
+6. Fallback: 128,000 tokens
 
-### 规则（Instructions）加载顺序
+---
 
-1. 全局规则：`~/.min-agent/rules.md`
-2. 项目规则（从当前目录向上查找首个命中）：
-   - `./AGENTS.md`
-   - `./RULES.md`
-   - `./CLAUDE.md`
-   - `./.min-agent/AGENTS.md`
-3. `~/.min-agent/config.json` 的 `instructions` 字段中声明的本地文件与远程 URL
+## Tools
 
-## Built-in Tools
+### Built-in
 
 | Tool | Description |
 |------|-------------|
-| `bash` | 执行 shell 命令 |
-| `read` | 读取文件 |
-| `write` | 写入/创建文件 |
-| `edit` | 文本替换编辑 |
-| `glob` | 按模式查找文件 |
-| `grep` | 按内容搜索 |
-| `web_search` | 联网搜索（SearXNG） |
-| `web_fetch` | 抓取网页内容（含 Firecrawl SPA 兜底） |
+| `bash` | Shell commands (async, timeout, Ctrl+C killable) |
+| `read` | Read files (with context-aware instruction discovery) |
+| `write` | Write/create files (with overwrite confirmation) |
+| `edit` | Search/replace precise editing |
+| `glob` | Find files by pattern |
+| `grep` | Search file contents with regex |
+| `web_search` | Web search via SearXNG |
+| `web_fetch` | Fetch URLs (with Firecrawl fallback for SPAs) |
+| `todo` | Task tracking with progress visibility |
+| `question` | Ask user for clarification |
+| `task` | Spawn parallel sub-agents |
+| `explore` | Deep codebase exploration (read-only sub-agent) |
+| `skill` | Load domain-specific instructions |
+| `memory_save` | Save information for future sessions |
+| `memory_search` | Search saved memories |
+| `memory_delete` | Remove a memory |
+| `codesearch` | Semantic code search via Exa (requires `EXA_API_KEY`) |
+
+### Sub-Agent System
+
+The `task` tool spawns independent sub-agents that:
+- Have their own context and tool access
+- Can run in parallel (call multiple tasks at once)
+- Are limited to 15 steps with doom loop detection
+- Cannot spawn further sub-agents (no recursion)
+
+The `explore` tool is a specialized read-only sub-agent for codebase exploration with configurable thoroughness (quick/medium/thorough).
+
+### Plugins
+
+Custom tools can be loaded from:
+- `.min-agent/tools/*.ts` (project-level)
+- `~/.min-agent/tools/*.ts` (global)
+
+```typescript
+// .min-agent/tools/deploy.ts
+export const deploy = {
+  description: "Deploy the application",
+  parameters: { env: { type: "string", description: "Target environment" } },
+  execute: async ({ env }) => {
+    // your logic
+    return `Deployed to ${env}`
+  }
+}
+```
 
-## 工具输出与截断
+---
+
+## MCP (Model Context Protocol)
+
+Connect external tool servers:
 
-内置工具与 MCP 返回的文本若超过约 **2000 行**或 **50KB（UTF-8）**，会将**全文**保存到 `~/.min-agent/tool-output/tool-*.txt`，并在返回内容中给出**预览 + 文件路径**；请用 `read`（`startLine`/`endLine`）或 `grep` 分段查看。
+```bash
+# Local stdio servers
+min-agent mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp
+min-agent mcp add fetch npx -y @modelcontextprotocol/server-fetch
 
-- **`bash`**：使用流式收集；内存中累计超过 **16MB** 会终止进程并提示改用重定向到文件。预览默认保留**输出尾部**（便于看日志）。
-- **其它文本类工具**（`read`、`grep`、`web_fetch`、`web_search`、`glob`、MCP）：超长时预览默认保留**开头**（`head`），全文仍在上述目录。
+# Remote HTTP servers
+min-agent mcp add remote-api --url https://mcp.example.com --token $TOKEN
+```
 
-该目录下旧文件会按修改时间做简单清理（约保留 7 天）。
+MCP tools are automatically namespaced (`servername_toolname`) and available in all modes.
 
-## Skill 安装
+Supports:
+- Stdio transport (local processes)
+- Streamable HTTP transport
+- SSE transport (legacy)
+- OAuth authentication detection
+- Auto-reconnect on failure
 
-会在以下目录递归查找 `**/SKILL.md`（**靠后的路径覆盖同名 skill**，即项目内优先于全局）：
+---
 
-1. `~/.agents/skills/`（用户全局，跨项目共享）
-2. `<cwd>/.min-agent/skills/`
-3. `<cwd>/.agent-demo/skills/`
-4. `<cwd>/.opencode/skills/`
-5. `<cwd>/.claude/skills/`
+## Skills
 
-创建目录与文件示例：
+Skills provide domain-specific instructions loaded on demand.
 
-```text
-~/.agents/skills/<your-skill>/SKILL.md
-.min-agent/skills/<your-skill>/SKILL.md
 ```
-
-`SKILL.md` 最小格式：
+.min-agent/skills/my-skill/SKILL.md
+```
 
 ```markdown
 ---
@@ -161,94 +271,89 @@ description: What this skill does
 # Instructions for the agent...
 ```
 
-可用命令：
+Discovery locations:
+- `.min-agent/skills/` (project)
+- `.opencode/skills/` (project)
+- `.claude/skills/` (project, compatibility)
 
-```bash
-min-agent skills list
-```
+---
 
-## MCP 安装
+## Rules (Instructions)
 
-配置在项目目录 `.min-agent/mcp.json`。
+Rules are injected into every conversation as system instructions.
 
-### 本地 MCP（stdio）
+| Source | Priority |
+|--------|----------|
+| `~/.min-agent/rules.md` | Global (always loaded) |
+| `./AGENTS.md` or `./RULES.md` | Project-level |
+| `.min-agent/AGENTS.md` | Project-level |
+| `config.instructions[]` | Paths or URLs |
 
-```bash
-min-agent mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp
-min-agent mcp add memory npx -y @modelcontextprotocol/server-memory
-min-agent mcp add custom --skip-check node ./my-mcp-server.js
-```
+**Context-aware**: When the agent reads a file, nearby `AGENTS.md`/`RULES.md` files are automatically discovered and injected.
 
-### 远程 MCP（HTTP）
+---
 
-通过 `url` 连接远端 MCP，使用 `@modelcontextprotocol/sdk` 的 **Streamable HTTP**；默认 `remoteTransport` 为 `auto`：先尝试 Streamable HTTP，失败再回退 **SSE**（兼容旧版 HTTP+SSE）。
+## Memory
+
+The agent remembers things across sessions:
 
 ```bash
-min-agent mcp add myremote --url https://api.example.com/mcp
-min-agent mcp add myremote --url https://api.example.com/mcp --token "$YOUR_BEARER_TOKEN"
-min-agent mcp add legacy --url https://old.example.com/sse --sse
-min-agent mcp add legacy --url https://old.example.com/sse --ext/event-stream
-min-agent mcp list
-min-agent mcp check
+min-agent memory add "I prefer functional style"
+min-agent memory add "Project uses PostgreSQL"
 ```
 
-手写配置示例：
+Or just tell the agent: "记住：我喜欢用中文回复" — it will automatically save the memory.
 
-```json
-{
-  "mcpServers": {
-    "remote-demo": {
-      "url": "https://example.com/mcp",
-      "remoteTransport": "auto",
-      "token": "optional-bearer-token",
-      "headers": { "X-Custom-Header": "value" },
-      "enabled": true
-    }
-  }
-}
-```
+Memories are injected into the system prompt so the agent always has access to them.
 
-- `token`：可选；若未设置 `Authorization`，会自动添加 `Bearer <token>`。
-- `remoteTransport`：`auto` | `streamable-http` | `sse`；CLI 中 `--sse` 等价于 `sse`。
+---
 
-说明：
+## Safety Features
 
-- `mcp add` 默认会先验证连通性；验证失败不会写入配置。
-- 离线或私有场景可使用 `--skip-check` 跳过添加时验证。
-- `mcp check` 会检查配置中所有服务（含远程），若有失败会返回非零退出码。
+- **Dangerous command confirmation**: `rm -rf`, `sudo`, `git push --force` etc. require approval
+- **File overwrite confirmation**: Existing files prompt before overwriting
+- **Doom loop detection**: Breaks infinite tool call loops (3 identical calls)
+- **Auto-compaction**: Prevents context overflow with structured summarization
+- **`--yes` / `-y` flag**: Skip all confirmations (for automation)
 
-聊天内可用：
+---
 
-```text
-/mcp
-```
+## Context Management
 
-## 常见问题（Troubleshooting）
+- **Real token tracking**: Uses API response usage data (not estimation)
+- **Auto-compaction**: Triggers at 75% of context window
+- **Structured summaries**: Goal/Progress/Decisions/Files format
+- **Incremental updates**: Updates existing summary instead of rewriting
+- **Tool output pruning**: Trims old tool outputs to save space
+- **Auto-continue**: After compaction, agent continues working automatically
 
-### 1) `AI_APICallError: Not Found`
+---
 
-常见原因是 provider `baseURL` 不匹配（例如 Ollama 未使用 `/v1` 路径）。  
-建议先执行：
+## HTTP API
 
-```bash
-min-agent setup
-min-agent models
-```
+Start with `min-agent serve`. Full reference: [docs/API.md](docs/API.md)
 
-确认可以正常拉取模型列表。
+Key endpoints:
+- `POST /v1/chat` — Chat (streaming SSE or JSON)
+- `GET /v1/sessions` — List sessions
+- `GET /v1/memory` — List memories
+- `GET /v1/mcp` — MCP status
+- `GET /v1/project` — Project scan
+- `POST /v1/chat/compact` — Manual compaction
 
-### 2) `models` 拉取为空
+---
 
-- 检查 `apiKey`、`baseURL` 是否正确
-- 检查网络或服务端是否可达
-- 检查服务是否实现 `/models`（Ollama 已做 `/v1/models` 兼容重试）
+## Environment Variables
 
-### 3) MCP 添加后不可用
+| Variable | Description |
+|----------|-------------|
+| `AGENT_MODEL` | Override default model |
+| `EXA_API_KEY` | Enable Exa code search tool |
+| `MIN_AGENT_SHOW_THINKING` | Set to `0` to hide thinking output |
+| `MIN_AGENT_SERVE_TOKEN` | API auth token for serve mode |
+| `MIN_AGENT_SERVE_CORS` | Enable CORS for serve mode |
 
-- 先 `min-agent mcp list` 看是否已配置
-- 在聊天内 `/mcp` 看连接状态（connected/disconnected/disabled）
-- **本地 stdio**：检查命令是否可执行（如 `npx` 是否可用）
-- **远程 URL**：确认地址为 `http(s)://`，必要时加 `--sse` 强制使用旧版 SSE 传输，或用 `mcp check` 查看具体错误信息
+---
 
 ## License