min-agent 0.1.4 → 0.1.6

package/README.md

@@ -1,254 +1,155 @@
 # min-agent
 
-轻量级 AI Agent，支持工具调用（读写文件、Shell、搜索）、MCP 与 Skill。  
-兼容 OpenAI 风格 API（OpenAI、Ollama、vLLM、MiniMax、DeepSeek 等）。
+Minimal AI coding agent for the terminal. Works with any OpenAI-compatible API.
 
-## 安装
-
-需要 **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 / 默认模型
-min-agent setup
-
-# 2) 单轮问答
-min-agent chat "hello"
-min-agent chat "read package.json and tell me the version"
-min-agent chat "帮我搜索一下最新的 AI 新闻"
-
-# 3) 进入多轮对话
-min-agent chat
+min-agent setup              # Configure provider
+min-agent chat "hello"       # Single message
+min-agent chat               # Interactive session
+min-agent code               # Project-aware coding mode
 ```
 
-## 首次运行会自动初始化
-
-在当前项目目录自动确保以下结构存在：
+---
 
-- `.min-agent/skills/`
-- `.min-agent/mcp.json`（默认 `{ "mcpServers": {} }`）
+## Commands
 
-用户全局技能目录 `~/.agents/skills/` 不会自动创建；若你自行创建并放入 `SKILL.md`，启动时会被扫描加载（见下文「Skill 安装」）。
+```bash
+min-agent chat [message]          # Chat (interactive if no message)
+min-agent chat -m <model> "msg"   # Override model
+min-agent chat -i img.png "msg"   # Attach image
+min-agent chat --resume <id>      # Resume session
+min-agent code                    # AI coding mode (project scan)
+min-agent setup                   # Configure API provider
+min-agent models                  # List available models
+min-agent history                 # List saved sessions
+min-agent rules                   # Show loaded rules
+min-agent rules edit              # Edit global rules
+min-agent memory                  # List memories
+min-agent memory add "text"       # Save memory
+min-agent mcp -h                  # MCP server management
+min-agent skills -h               # Skills management
+min-agent serve                   # Start HTTP API server
+```
 
-## CLI 命令
+## Interactive 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 history |
+| `/compact` | Force compaction |
+| `/model [name]` | Show/change model |
+| `/memory [text]` | List/save memory |
+| `/tokens` | Context usage |
+| `/paste [text]` | Clipboard image |
+| `/path` | Working directory |
+| `/help` | All commands |
+| `/exit` | Exit |
+
+**Ctrl+C** interrupts current generation.
+
+---
+
+## Configuration
+
+All config in `~/.min-agent/`:
 
 ```json
+// ~/.min-agent/config.json
 {
   "provider": {
     "type": "openai-compatible",
     "baseURL": "https://api.openai.com/v1",
     "apiKey": "sk-...",
-    "defaultModel": "gpt-4o"
-  }
+    "defaultModel": "gpt-5.5",
+    "contextWindow": 128000
+  },
+  "instructions": ["./docs/rules.md"],
+  "disabledSkills": []
 }
 ```
 
-说明：
-
-- `setup` 时根据填写信息自动拉取模型列表。
-- Ollama 支持填 `http://host:11434` 或 `http://host:11434/v1`，会自动兼容。
-
-### MCP 配置
+Provider types: `openai-compatible` | `openai` | `ollama`
 
-项目级配置：`.min-agent/mcp.json`
-
-### 规则（Instructions）加载顺序
-
-1. 全局规则：`~/.min-agent/rules.md`
-2. 项目规则（从当前目录向上查找首个命中）：
-   - `./AGENTS.md`
-   - `./RULES.md`
-   - `./CLAUDE.md`
-   - `./.min-agent/AGENTS.md`
-3. `~/.min-agent/config.json` 的 `instructions` 字段中声明的本地文件与远程 URL
-
-## Built-in Tools
-
-| Tool | Description |
-|------|-------------|
-| `bash` | 执行 shell 命令 |
-| `read` | 读取文件 |
-| `write` | 写入/创建文件 |
-| `edit` | 文本替换编辑 |
-| `glob` | 按模式查找文件 |
-| `grep` | 按内容搜索 |
-| `web_search` | 联网搜索（SearXNG） |
-| `web_fetch` | 抓取网页内容（含 Firecrawl SPA 兜底） |
-
-## 工具输出与截断
-
-内置工具与 MCP 返回的文本若超过约 **2000 行**或 **50KB（UTF-8）**，会将**全文**保存到 `~/.min-agent/tool-output/tool-*.txt`，并在返回内容中给出**预览 + 文件路径**；请用 `read`（`startLine`/`endLine`）或 `grep` 分段查看。
-
-- **`bash`**：使用流式收集；内存中累计超过 **16MB** 会终止进程并提示改用重定向到文件。预览默认保留**输出尾部**（便于看日志）。
-- **其它文本类工具**（`read`、`grep`、`web_fetch`、`web_search`、`glob`、MCP）：超长时预览默认保留**开头**（`head`），全文仍在上述目录。
-
-该目录下旧文件会按修改时间做简单清理（约保留 7 天）。
-
-## Skill 安装
+---
 
-会在以下目录递归查找 `**/SKILL.md`（**靠后的路径覆盖同名 skill**，即项目内优先于全局）：
+## MCP
 
-1. `~/.agents/skills/`（用户全局，跨项目共享）
-2. `<cwd>/.min-agent/skills/`
-3. `<cwd>/.agent-demo/skills/`
-4. `<cwd>/.opencode/skills/`
-5. `<cwd>/.claude/skills/`
+```bash
+min-agent mcp add <name> <cmd...>              # Local stdio
+min-agent mcp add <name> --url <url> --token T # Remote HTTP
+min-agent mcp list                             # List (name + status)
+min-agent mcp info <name>                      # Details
+min-agent mcp enable/disable <name...>         # Toggle
+min-agent mcp remove <name>                    # Remove
+min-agent mcp check                            # Test connectivity
+```
 
-创建目录与文件示例：
+## Skills
 
-```text
-~/.agents/skills/<your-skill>/SKILL.md
-.min-agent/skills/<your-skill>/SKILL.md
+```bash
+min-agent skills list                          # List (name + status)
+min-agent skills info <name>                   # Details
+min-agent skills enable/disable <name...>      # Toggle
 ```
 
-`SKILL.md` 最小格式：
+Create: `.min-agent/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`
 
 ```markdown
 ---
 name: my-skill
-description: What this skill does
+description: What it does
 ---
-
-# Instructions for the agent...
+# Instructions...
 ```
 
-可用命令：
-
-```bash
-min-agent skills list
-```
+## Rules
 
-## MCP 安装
+| Source | Scope |
+|--------|-------|
+| `~/.min-agent/rules.md` | Global |
+| `./AGENTS.md` or `./RULES.md` | Project |
+| `config.instructions[]` | Custom paths/URLs |
 
-配置在项目目录 `.min-agent/mcp.json`。
-
-### 本地 MCP（stdio）
-
-```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
-```
-
-### 远程 MCP（HTTP）
-
-通过 `url` 连接远端 MCP，使用 `@modelcontextprotocol/sdk` 的 **Streamable HTTP**；默认 `remoteTransport` 为 `auto`：先尝试 Streamable HTTP，失败再回退 **SSE**（兼容旧版 HTTP+SSE）。
-
-```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
-```
+## Plugins
 
-手写配置示例：
+Custom tools: `.min-agent/tools/*.ts` or `~/.min-agent/tools/*.ts`
 
-```json
-{
-  "mcpServers": {
-    "remote-demo": {
-      "url": "https://example.com/mcp",
-      "remoteTransport": "auto",
-      "token": "optional-bearer-token",
-      "headers": { "X-Custom-Header": "value" },
-      "enabled": true
-    }
-  }
+```typescript
+export const myTool = {
+  description: "...",
+  parameters: { arg: { type: "string", description: "..." } },
+  execute: async ({ arg }) => "result"
 }
 ```
 
-- `token`：可选；若未设置 `Authorization`，会自动添加 `Bearer <token>`。
-- `remoteTransport`：`auto` | `streamable-http` | `sse`；CLI 中 `--sse` 等价于 `sse`。
-
-说明：
-
-- `mcp add` 默认会先验证连通性；验证失败不会写入配置。
-- 离线或私有场景可使用 `--skip-check` 跳过添加时验证。
-- `mcp check` 会检查配置中所有服务（含远程），若有失败会返回非零退出码。
-
-聊天内可用：
-
-```text
-/mcp
-```
-
-## 常见问题（Troubleshooting）
-
-### 1) `AI_APICallError: Not Found`
+---
 
-常见原因是 provider `baseURL` 不匹配（例如 Ollama 未使用 `/v1` 路径）。  
-建议先执行：
+## HTTP API
 
 ```bash
-min-agent setup
-min-agent models
+min-agent serve [--port 8787]
 ```
 
-确认可以正常拉取模型列表。
-
-### 2) `models` 拉取为空
+Full reference: [docs/API.md](docs/API.md)
 
-- 检查 `apiKey`、`baseURL` 是否正确
-- 检查网络或服务端是否可达
-- 检查服务是否实现 `/models`（Ollama 已做 `/v1/models` 兼容重试）
+---
 
-### 3) MCP 添加后不可用
+## Environment Variables
 
-- 先 `min-agent mcp list` 看是否已配置
-- 在聊天内 `/mcp` 看连接状态（connected/disconnected/disabled）
-- **本地 stdio**：检查命令是否可执行（如 `npx` 是否可用）
-- **远程 URL**：确认地址为 `http(s)://`，必要时加 `--sse` 强制使用旧版 SSE 传输，或用 `mcp check` 查看具体错误信息
+| Variable | Description |
+|----------|-------------|
+| `EXA_API_KEY` | Enable Exa code search |
+| `MIN_AGENT_SHOW_THINKING` | `0` to hide thinking |
+| `MIN_AGENT_SERVE_TOKEN` | API auth token |
+| `MIN_AGENT_SERVE_CORS` | `1` to enable CORS |
 
 ## License