min-agent 0.3.0 → 0.4.1

package/README.md

@@ -1,283 +1,221 @@
+<div align="center">
+
 # min-agent
 
-Minimal AI coding agent for the terminal. Works with any OpenAI-compatible API.
+一款在终端里运行的 AI 编程助手 · An AI coding agent that lives in your terminal
+
+[![English](https://img.shields.io/badge/lang-English-blue.svg)](#english)
+[![简体中文](https://img.shields.io/badge/lang-简体中文-red.svg)](#简体中文)
+
+</div>
+
+<br>
+
+<div align="center">
+
+⬇️ 请选择你的语言 / Please choose your language ⬇️
+
+**➡️ [English](#english)　　➡️ [简体中文](#简体中文)**
+
+</div>
+
+<br><br>
+
+<a id="english"></a>
+
+# 🇬🇧 English
+
+> A minimal AI coding agent for your terminal. Works with OpenAI, Ollama, and any OpenAI-compatible provider.
 
-## Install
+<sub>[🔝 Back to language selector](#min-agent) · [🇨🇳 Switch to 简体中文](#简体中文)</sub>
+
+## Get Started
 
 ```bash
 npm install -g min-agent
+min-agent setup      # Configure your AI provider
+min-agent             # Start chatting
 ```
 
-## Quick Start
+## Basic Usage
 
 ```bash
-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                       # Start an interactive session
+min-agent "your message"        # Start a session and send a message immediately
+min-agent exec "your message"   # Ask a single question, then exit
+min-agent --resume <id>         # Resume a previous session
+min-agent history                # List saved sessions
+min-agent models                 # List available models
+min-agent update                 # Upgrade to the latest version
 ```
 
----
-
-## Commands
+Attach an image or pick a specific model/provider for one message:
 
 ```bash
-min-agent chat [message]          # Chat (interactive if no message)
-min-agent chat -m <model> "msg"   # Override model
-min-agent chat --provider <name> "msg"   # Use a specific provider
-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 history delete <id>     # Delete a session
-min-agent history rename <id> <t> # Rename a session
-min-agent history export <id> [-o file]  # Export a session as JSON
-min-agent update                  # Check for updates and upgrade
-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
+min-agent -i photo.png "what's in this image?"
+min-agent -m gpt-5.5 "your message"
+min-agent --provider anthropic "your message"
 ```
 
-## Interactive Commands
+## While Chatting
 
-Type `/` in the interactive session to pop up a command menu (↑↓ navigate, Enter select, Esc close). All commands also work by typing them directly:
+Type `/` to open a command menu. Use **↑ / ↓** to recall previous messages.
 
 | Command | Description |
-|---------|-------------|
-| `/clear` | Clear history |
-| `/compact` | Force compaction |
-| `/model [name]` | Interactive model picker (↑↓ navigate, Enter confirm) |
-| `/provider [name]` | List/switch provider |
-| `/plan` | Toggle read-only plan mode |
-| `/memory [text]` | List/save memory |
-| `/tokens` | Context usage & cost |
-| `/budget [n]` | Show/set cost budget (USD) |
-| `/undo` | Undo last turn |
-| `/redo` | Resend last message |
-| `/diff` | Show working tree diff |
-| `/sessions` | List saved sessions |
-| `/rename <title>` | Rename current session |
+|---|---|
+| `/new` | Start a new session |
+| `/model` | Switch model |
+| `/provider` | Switch provider |
+| `/plan` | Toggle plan mode (look, don't touch) |
+| `/undo` | Undo the last turn |
+| `/diff` | Show file changes made so far |
+| `/sessions` | List or switch sessions |
 | `/attach <path>` | Attach a local image |
-| `/paste [text]` | Clipboard image |
-| `/mcp` | MCP server status |
-| `/skills` | List skills; `/skills info <name>` to view; `/skills enable\|disable <name>` to toggle |
-| `/models` | List available models |
-| `/path` | Working directory |
-| `/help` | All commands |
+| `/mcp` | Show connected MCP servers |
+| `/skills` | Manage skills |
+| `/tokens` | Usage and estimated cost |
+| `/help` | Show all commands |
 | `/exit` | Exit |
 
-**Ctrl+C** interrupts current generation.
+Shortcuts: **Ctrl+C** clears the input (press twice to exit) · **Ctrl+B** selects text to copy · mouse drag-select also copies on release.
 
-**鼠标拖拽** 在消息区拖拽选择文本，松开自动复制到剪贴板（状态栏会短暂提示"已复制"）。
+## Staying in Control
 
----
-
-## Configuration
+min-agent asks for confirmation before risky actions by default.
 
-All config in `~/.min-agent/`:
-
-```json
-// ~/.min-agent/config.json
-{
-  "providers": [
-    {
-      "name": "default",
-      "type": "openai-compatible",
-      "baseURL": "https://api.openai.com/v1",
-      "apiKey": "sk-...",
-      "defaultModel": "gpt-5.5",
-      "contextWindow": 128000
-    }
-  ],
-  "activeProvider": "default",
-  "webSearchURL": "https://your-searxng.example.com",
-  "serperApiKey": "your-serper-key",
-  "instructions": ["./docs/rules.md"],
-  "disabledSkills": [],
-  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
-  "sampling": { "temperature": 0.7, "maxTokens": 4096 },
-  "budget": { "maxCostUSD": 5 }
-}
+```bash
+min-agent permission                 # Show current setting
+min-agent --permission ask           # Confirm before risky actions (default)
+min-agent --permission accept-edits  # Auto-approve file edits only
+min-agent --permission allow-all     # Auto-approve everything — use with care
 ```
 
-Project-level config lives in `.min-agent/config.json` and currently holds skill state only:
+You can also limit what it's allowed to touch on your machine:
 
-```json
-// .min-agent/config.json
-{
-  "disabledSkills": ["noisy-skill"],
-  "enabledSkills": ["skill-disabled-globally"]
-}
+```bash
+min-agent sandbox            # Show current restriction level
+min-agent sandbox off        # No restriction (default)
+min-agent sandbox workspace  # Only allow changes inside the current folder
 ```
 
-`pricing` 覆盖模型价格（USD / 1M tokens），用于成本估算；未配置时自动从 models.dev 获取。
+## Configuration
+
+Run `min-agent setup` for a guided setup — this is the easiest way to add or switch AI providers.
+
+Settings live in `~/.min-agent/config.json` (global). A project can have its own `.min-agent/config.json` that only applies there.
 
-Multiple providers are supported: add entries to `providers` and set `activeProvider` (or use `min-agent setup`). Old single-provider configs are migrated automatically on first run.
+## Extending It
 
-`sampling` sets defaults for temperature/maxTokens/topP (overridable per request). `budget.maxCostUSD` aborts the current run as soon as cumulative cost exceeds the limit (checked after each model step).
+- **MCP servers** — connect external tools and data sources: `min-agent mcp -h`
+- **Skills** — reusable instructions the agent loads automatically: `min-agent skills -h`
+- **Project rules** — add an `AGENTS.md` or `RULES.md` file to your project for custom instructions; use `~/.min-agent/rules.md` for global ones.
 
-Provider types: `openai-compatible` | `openai` | `ollama`
+## API Access
 
-Logs: `~/.min-agent/logs/min-agent.YYYY-MM-DD.log` (rotated daily, kept 7 days)
+`min-agent serve` starts a local HTTP API server so other apps can talk to min-agent. Reference: [docs/API.md](docs/API.md)
+
+## License
+
+MIT
+
+<br>
 
 ---
 
-## MCP
+<br>
 
-```bash
-min-agent mcp add <name> <cmd...>              # Local stdio
-min-agent mcp add <name> <cmd...> --env K=V    # Local stdio with env vars
-min-agent mcp add <name> --url <url> --token T # Remote HTTP
-min-agent mcp add <name> --url <url> --sse     # Legacy SSE transport
-min-agent mcp add <name> --url <url> --streamable-http  # Force streamable HTTP
-min-agent mcp add <name> ... --project         # Save to .min-agent/mcp.json (this repo only)
-min-agent mcp add <name> ... --timeout 10000   # Connection/call timeout in ms
-min-agent mcp list                             # List (name + status + scope)
-min-agent mcp info <name>                      # Details
-min-agent mcp enable/disable <name...> [--project]  # Toggle
-min-agent mcp remove <name> [--project]        # Remove
-min-agent mcp check                            # Test connectivity
-```
+<a id="简体中文"></a>
 
-配置合并规则：`~/.min-agent/mcp.json`（全局）与 `.min-agent/mcp.json`（项目）按名称合并，项目条目覆盖同名全局条目；`mcp list` 会标注 `[project]`。
-
-远程服务器如需 OAuth 登录（部分云端 MCP），在 mcp.json 里加 `"oauth": {}`（或用 `"clientId"`/`"clientSecret"`/`"scope"` 显式指定），连接时自动打开浏览器完成授权，令牌缓存在 `~/.min-agent/mcp-oauth/`。`"oauth": false` 关闭。
-
-mcp.json 完整字段（`min-agent mcp add` 只生成子集，其余手写）：
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
-      "environment": { "KEY": "VALUE" },
-      "enabled": true,
-      "connectTimeout": 10000,
-      "callTimeout": 30000
-    },
-    "remote": {
-      "url": "https://mcp.example.com/mcp",
-      "remoteTransport": "auto",
-      "token": "bearer-token",
-      "headers": { "X-API-Key": "..." },
-      "oauth": {},
-      "connectTimeout": 15000,
-      "callTimeout": 30000
-    }
-  }
-}
-```
+# 🇨🇳 简体中文
+
+> 一款可在终端里运行的极简 AI 编程助手，支持 OpenAI、Ollama 以及任何兼容 OpenAI 接口的服务商。
 
-- `remoteTransport`：`auto`（默认，先 streamable-http 再 sse）、`streamable-http`、`sse`
-- `timeout`：连接与调用共用的旧字段；`connectTimeout` / `callTimeout` 可分别覆盖
-- 连接失败时错误信息会带上服务器 stderr 的最后几行，便于排查
+<sub>[🔝 返回语言选择](#min-agent) · [🇬🇧 Switch to English](#english)</sub>
 
-## Skills
+## 快速上手
 
 ```bash
-min-agent skills list                          # List (status + scope + description + path)
-min-agent skills list --json                   # Machine-readable output
-min-agent skills info <name>                   # Details + content
-min-agent skills info <name> --json            # Details as JSON
-min-agent skills new <name>                    # Create a skill scaffold (.min-agent/skills/<name>/)
-min-agent skills new <name> --global           # Create in ~/.agents/skills/<name>/
-min-agent skills disable <name...>             # Disable everywhere (global)
-min-agent skills disable <name...> --project   # Disable in this repo only
-min-agent skills enable <name...> --project    # Re-enable here even if disabled globally
+npm install -g min-agent
+min-agent setup      # 配置你的 AI 服务商
+min-agent             # 开始对话
 ```
 
-Scope: project state lives in `.min-agent/config.json`, global state in `~/.min-agent/config.json`.
-Project wins over global, so disabling a repo-local skill never affects other repos.
+## 基本用法
 
-In the interactive session: `/skills`, `/skills info <name>`, `/skills disable <name> [--project]`, `/skills enable <name> [--project]`.
-Type `/skills ` and press Tab to complete subcommands and skill names.
+```bash
+min-agent                       # 进入交互会话
+min-agent "你的消息"              # 进入交互会话并立即发送消息
+min-agent exec "你的消息"         # 单次提问后自动退出
+min-agent --resume <id>         # 恢复之前的会话
+min-agent history                # 查看已保存的会话
+min-agent models                 # 查看可用模型
+min-agent update                 # 升级到最新版本
+```
 
-Create: `min-agent skills new <name>` scaffolds a `SKILL.md` template into `.min-agent/skills/<name>/` (add `--global` for `~/.agents/skills/`), or write it by hand:
+为单条消息附带图片，或指定模型/服务商：
 
-```markdown
----
-name: my-skill
-description: What it does
-# optional
-version: 1.0.0
-allowed-tools: [read, grep]
-metadata:
-  requires:
-    bins: ["some-cli"]
----
-# Instructions...
+```bash
+min-agent -i photo.png "这张图片是什么？"
+min-agent -m gpt-5.5 "你的消息"
+min-agent --provider anthropic "你的消息"
 ```
 
-- `description` may use a YAML block scalar (`|` / `>`) for multi-line text.
-- Discovery paths, in override order: `~/.agents/skills/` → `.min-agent/skills/` → `.agents/skills/` → `.opencode/skills/` → `.claude/skills/`. Symlinked skill directories are followed, so one shared skill library can be linked into several of these.
-- A same-named skill in a later path overrides the earlier one; within one path the top-level `SKILL.md` wins over a nested copy.
-- `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces the discovery list entirely.
-- Files next to `SKILL.md` (including subdirectories such as `scripts/`) are listed for the agent when the skill loads; `metadata.requires.bins` entries missing from `PATH` are reported.
+## 对话中的操作
 
-## Rules
+输入 `/` 弹出命令菜单。使用 **↑ / ↓** 翻看之前的消息。
 
-| Source | Scope |
-|--------|-------|
-| `~/.min-agent/rules.md` | Global |
-| `./AGENTS.md` or `./RULES.md` | Project |
-| `config.instructions[]` | Custom paths/URLs |
+| 命令 | 说明 |
+|---|---|
+| `/new` | 开始新会话 |
+| `/model` | 切换模型 |
+| `/provider` | 切换服务商 |
+| `/plan` | 切换"计划模式"（只看不改） |
+| `/undo` | 撤销上一轮操作 |
+| `/diff` | 查看当前已产生的文件改动 |
+| `/sessions` | 查看或切换会话 |
+| `/attach <路径>` | 附加本地图片 |
+| `/mcp` | 查看已连接的 MCP 服务 |
+| `/skills` | 管理技能 |
+| `/tokens` | 查看用量与预估费用 |
+| `/help` | 查看全部命令 |
+| `/exit` | 退出 |
 
-## Plugins
+快捷键：**Ctrl+C** 清空输入框（连按两次退出）· **Ctrl+B** 选中文本以复制 · 也支持鼠标拖拽选中并自动复制。
 
-Custom tools: `.min-agent/tools/*.ts` or `~/.min-agent/tools/*.ts`
+## 掌控风险
 
-```typescript
-export const myTool = {
-  description: "...",
-  parameters: { arg: { type: "string", description: "..." } },
-  execute: async ({ arg }) => "result"
-}
-```
+min-agent 默认会在执行有风险的操作前先询问你。
 
-```typescript
-export const dockerPs = {
-  description: "List running docker containers",
-  parameters: { limit: { type: "number", description: "Max containers to show" } },
-  execute: async ({ limit }) => {
-    const { execSync } = await import("child_process")
-    return execSync(`docker ps --format "table {{.Names}}\t{{.Status}}" --limit ${limit ?? 10}`, {
-      encoding: "utf-8",
-    })
-  }
-}
+```bash
+min-agent permission                 # 查看当前设置
+min-agent --permission ask           # 有风险操作前先询问（默认）
+min-agent --permission accept-edits  # 仅自动批准文件修改
+min-agent --permission allow-all     # 自动批准所有操作 —— 请谨慎使用
 ```
 
----
-
-## HTTP API
+也可以限制它能在你电脑上访问的范围：
 
 ```bash
-min-agent serve [--port 8787]
+min-agent sandbox            # 查看当前限制级别
+min-agent sandbox off        # 不限制（默认）
+min-agent sandbox workspace  # 仅允许修改当前项目文件夹内的内容
 ```
 
-Full reference: [docs/API.md](docs/API.md)
+## 配置
 
----
+运行 `min-agent setup` 即可通过引导式流程完成配置，这是添加或切换 AI 服务商最简单的方式。
+
+配置保存在 `~/.min-agent/config.json`（全局生效）。也可以在某个项目下单独创建 `.min-agent/config.json`，仅对该项目生效。
+
+## 扩展能力
+
+- **MCP 服务**：连接外部工具与数据源，运行 `min-agent mcp -h` 了解详情
+- **技能（Skills）**：可自动加载的可复用指令集，运行 `min-agent skills -h` 了解详情
+- **项目规则**：在项目根目录添加 `AGENTS.md` 或 `RULES.md` 编写自定义指令；全局规则写入 `~/.min-agent/rules.md`
+
+## API 接入
 
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `EXA_API_KEY` | Enable Exa code search |
-| `MIN_AGENT_SERPER_API_KEY` | Serper key for `search_web` (default backend; takes precedence over `serperApiKey` in config) |
-| `MIN_AGENT_SEARXNG_URL` | Use SearXNG instead of Serper for `search_web` (takes precedence over `webSearchURL` in config) |
-| `MIN_AGENT_SEARXNG_FALLBACK_ENGINES` | Engines retried when the SearXNG instance's default engines return nothing (default `google,bing`; empty string disables the retry) |
-| `MIN_AGENT_FIRECRAWL_URL` | Firecrawl instance for `web_fetch` (takes precedence over `webFetchURL` in config) |
-| `MIN_AGENT_SKILLS_DIRS` | `:`-separated dirs that replace the default skill discovery list |
-| `MIN_AGENT_SHOW_THINKING` | `0` to hide thinking |
-| `MIN_AGENT_SERVE_TOKEN` | API auth token |
-| `MIN_AGENT_SERVE_CORS` | `1` to enable CORS (without a token, only localhost origins are allowed) |
+`min-agent serve` 可启动本地 HTTP API 服务，供其他应用调用。完整说明见 [docs/API.md](docs/API.md)
 
 ## License