min-agent 0.2.1 → 0.3.0

package/README.md

@@ -24,12 +24,17 @@ min-agent code               # Project-aware coding mode
 ```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
@@ -41,20 +46,36 @@ min-agent serve                   # Start HTTP API server
 
 ## Interactive Commands
 
+Type `/` in the interactive session to pop up a command menu (↑↓ navigate, Enter select, Esc close). All commands also work by typing them directly:
+
 | Command | Description |
 |---------|-------------|
 | `/clear` | Clear history |
 | `/compact` | Force compaction |
-| `/model [name]` | Show/change model |
+| `/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 |
+| `/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 |
+| `/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 |
 | `/exit` | Exit |
 
 **Ctrl+C** interrupts current generation.
 
+**鼠标拖拽** 在消息区拖拽选择文本，松开自动复制到剪贴板（状态栏会短暂提示"已复制"）。
+
 ---
 
 ## Configuration
@@ -64,52 +85,141 @@ All config in `~/.min-agent/`:
 ```json
 // ~/.min-agent/config.json
 {
-  "provider": {
-    "type": "openai-compatible",
-    "baseURL": "https://api.openai.com/v1",
-    "apiKey": "sk-...",
-    "defaultModel": "gpt-5.5",
-    "contextWindow": 128000
-  },
+  "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": []
+  "disabledSkills": [],
+  "pricing": { "gpt-5.5": { "inputPerMillion": 1.25, "outputPerMillion": 10 } },
+  "sampling": { "temperature": 0.7, "maxTokens": 4096 },
+  "budget": { "maxCostUSD": 5 }
+}
+```
+
+Project-level config lives in `.min-agent/config.json` and currently holds skill state only:
+
+```json
+// .min-agent/config.json
+{
+  "disabledSkills": ["noisy-skill"],
+  "enabledSkills": ["skill-disabled-globally"]
 }
 ```
 
+`pricing` 覆盖模型价格（USD / 1M tokens），用于成本估算；未配置时自动从 models.dev 获取。
+
+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.
+
+`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).
+
 Provider types: `openai-compatible` | `openai` | `ollama`
 
+Logs: `~/.min-agent/logs/min-agent.YYYY-MM-DD.log` (rotated daily, kept 7 days)
+
 ---
 
 ## MCP
 
 ```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 list                             # List (name + status)
+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...>         # Toggle
-min-agent mcp remove <name>                    # Remove
+min-agent mcp enable/disable <name...> [--project]  # Toggle
+min-agent mcp remove <name> [--project]        # Remove
 min-agent mcp check                            # Test connectivity
 ```
 
+配置合并规则：`~/.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
+    }
+  }
+}
+```
+
+- `remoteTransport`：`auto`（默认，先 streamable-http 再 sse）、`streamable-http`、`sse`
+- `timeout`：连接与调用共用的旧字段；`connectTimeout` / `callTimeout` 可分别覆盖
+- 连接失败时错误信息会带上服务器 stderr 的最后几行，便于排查
+
 ## Skills
 
 ```bash
-min-agent skills list                          # List (name + status)
-min-agent skills info <name>                   # Details
-min-agent skills enable/disable <name...>      # Toggle
+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
 ```
 
-Create: `.min-agent/skills/<name>/SKILL.md` or `~/.agents/skills/<name>/SKILL.md`
+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.
+
+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...
 ```
 
+- `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 |
@@ -130,6 +240,19 @@ export const myTool = {
 }
 ```
 
+```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",
+    })
+  }
+}
+```
+
 ---
 
 ## HTTP API
@@ -147,9 +270,14 @@ Full reference: [docs/API.md](docs/API.md)
 | 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 |
+| `MIN_AGENT_SERVE_CORS` | `1` to enable CORS (without a token, only localhost origins are allowed) |
 
 ## License