min-agent 0.4.0 → 0.5.0

package/README.md

@@ -1,366 +1,251 @@
+<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.
+
+<sub>[🔝 Back to language selector](#min-agent) · [🇨🇳 Switch to 简体中文](#简体中文)</sub>
 
-## Install
+## Get Started
 
 ```bash
 npm install -g min-agent
-min-agent update              # Upgrade to the latest npm release
+min-agent setup      # Configure your AI provider
+min-agent             # Start chatting
 ```
 
-## Quick Start
+## Basic Usage
 
 ```bash
-min-agent setup              # Configure provider
-min-agent                    # Interactive session
-min-agent "hello"            # Interactive session, send immediately
-min-agent exec "hello"       # One-shot, then exit
-min-agent exec --resume <id> "continue"  # Continue a saved one-shot session
+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                         # Interactive session
-min-agent "msg"                   # Interactive session, send immediately
-min-agent exec "msg"              # One-shot, then exit
-min-agent exec --resume <id> "msg" # Continue a saved one-shot session
-min-agent -m <model> "msg"        # Override model
-min-agent --provider <name> "msg" # Use a specific provider
-min-agent -i img.png "msg"        # Attach image
-min-agent --resume <id>           # Resume session
-min-agent chat | code             # Same as interactive session (compat)
-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                  # Upgrade to the latest npm release
-min-agent rules                   # Show loaded rules
-min-agent rules edit              # Edit global rules
-min-agent memory                  # List project + global memories
-min-agent memory add "text"       # Save memory (project if .min-agent exists)
-min-agent memory add "text" --project
-min-agent memory add "text" --global
-min-agent mcp -h                  # MCP server management
-min-agent skills -h               # Skills management
-min-agent sandbox                 # Show isolation
-min-agent sandbox off             # Write isolation to config and exit
-min-agent --sandbox workspace "msg"  # This session only; does not write config
-min-agent sandbox network deny --project
-min-agent permission              # Show confirmation mode
-min-agent --permission ask        # Write confirmation mode to config and exit
-min-agent --permission accept-edits --project
-min-agent --permission allow-all "msg"  # This session only
-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 (type to filter, Tab/Enter select, Esc close). **↑↓** in the input box recall previously sent messages, skipping slash commands. All commands also work by typing them directly:
+Type `/` to open a command menu. Use **↑ / ↓** to recall previous messages.
 
 | Command | Description |
-|---------|-------------|
-| `/new` | Start a new session (keeps the current one) |
-| `/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 (`--project` writes to this repo) |
-| `/tokens` | Context occupancy, session totals & cost |
-| `/budget [n]` | Show/set cost budget (USD; `--project` writes to this repo) |
-| `/permission` | Show/set confirmation (`ask` / `accept-edits` / `allow-all`; `--project` writes to this repo) |
-| `/sandbox` | Show/set isolation (`off` / `workspace` / `strict`; `--project` writes to this repo) |
-| `/undo` | Undo last turn |
-| `/redo` | Resend last message |
-| `/diff` | Show working tree diff |
-| `/sessions [id]` | List or switch saved sessions |
-| `/resume [id]` | Same as `/sessions` |
-| `/reload` | Reload rules |
-| `/rename <title>` | Rename current session |
+|---|---|
+| `/new` | Start a new session |
+| `/model` | Switch model |
+| `/provider` | Switch provider |
+| `/plan` | Toggle plan mode (look, don't touch) |
+| `/think` | Choose thinking intensity |
+| `/memory` | Turn memory on/off, or save a note |
+| `/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** clears the input box and saves it to history (↑ / ↓ to recall). Press **Ctrl+C twice** on an empty input to exit; the current session is saved. While generating, it interrupts the current run. **Ctrl+B** enters message selection mode (arrow keys expand the selection, Enter copies, Esc exits). **↑ / ↓** in the input box recall previously typed or sent messages. **Home / End** move to the start or end of the line.
-
-授权确认时 **[y] / [N]** 始终留在窗口底部；详情过长时用 **↑↓** 或 **PageUp / PageDown** 滚动，不必翻到消息区底部。提问输入行同样固定可见。
-
-**鼠标** 在消息区拖拽选择文本，松开自动复制；双击选词、三击选中该条可见内容。复制时不含 `>` 与工具前缀。状态栏会短暂提示"已复制"。
-
----
+Shortcuts: **Ctrl+C** clears the input (press twice to exit) · **Ctrl+V** pastes an image · a multi-line paste becomes a snippet · **Ctrl+B** selects text to copy · mouse drag-select also copies on release · click a tool or thinking block to expand or collapse it.
 
-## Configuration
+## Staying in Control
 
-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": 1000000
-    }
-  ],
-  "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 }
-}
-```
+min-agent asks for confirmation before risky actions by default.
 
-Project-level config lives in `.min-agent/config.json`. It can override skill state and selected global settings; API keys stay in `~/.min-agent/config.json` only:
-
-```json
-// .min-agent/config.json
-{
-  "disabledSkills": ["noisy-skill"],
-  "enabledSkills": ["skill-disabled-globally"],
-  "activeProvider": "default",
-  "defaultModel": "gpt-5.5",
-  "sampling": { "temperature": 0.4 },
-  "budget": { "maxCostUSD": 2 },
-  "permission": "ask",
-  "sandbox": { "mode": "workspace", "network": "allow" },
-  "compaction": { "autoContinue": false }
-}
+```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 values overlay the global file when present (`sampling` / `budget` / `sandbox` / `compaction` / `agent` merge field-by-field). `/budget 5 --project` writes the project budget. `/sandbox workspace --project` writes project isolation. `/permission accept-edits --project` writes project confirmation mode.
-
-Isolation is **off by default**. `--permission` / `--yes` only skip confirmations; they do not change isolation.
-
-`--permission ask|accept-edits|allow-all` without a message writes config and exits (same as `min-agent permission …`). With a message, `--resume`, `--model`, or `--provider`, it only overrides that session. `--yes` / `-y` is this session only (same as `--permission allow-all`) and does not write config.
+You can also limit what it's allowed to touch on your machine:
 
 ```bash
-min-agent permission                         # show current confirmation mode
-min-agent --permission ask                   # write global config, then exit
-min-agent --permission accept-edits --project
-min-agent --permission allow-all "msg"       # this session only; does not write config
+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
 ```
 
-`ask` (default) prompts before dangerous operations. `accept-edits` auto-approves file writes and still prompts for dangerous commands. `allow-all` auto-approves everything.
+## Memory
 
-Without a message, `--sandbox` / `--network` write config and exit (same as `min-agent sandbox …`). With a message, `--resume`, `--model`, or `--provider`, they only override that session:
+Remembered notes are off by default. Turn them on when you want facts to persist across sessions:
 
 ```bash
-min-agent sandbox                      # show current isolation
-min-agent --sandbox off                # write global config, then exit
-min-agent --sandbox workspace --project
-min-agent --sandbox workspace "msg"    # this session only; does not write config
-min-agent sandbox network deny
-```
-
-```json
-"sandbox": {
-  "mode": "workspace",
-  "network": "allow",
-  "extraWriteRoots": ["/path/allowed-to-write"],
-  "extraReadRoots": []
-}
+min-agent memory                 # Show the switch and stored notes
+min-agent memory on              # Turn memory on (writes config)
+min-agent --memory on            # Same; with a message, this session only
+min-agent memory add "prefer bun"
 ```
 
-`mode`: `off` (default) | `workspace` (write only in the working directory, plus temp/cache) | `strict` (read and write only there). `extraWriteRoots` / `extraReadRoots` add extra directories when isolation is on. Env: `MIN_AGENT_SANDBOX`, `MIN_AGENT_SANDBOX_NETWORK`.
-
-Project memories live in `.min-agent/memory.json`; global memories in `~/.min-agent/memory.json`. The agent reads project first, then global. Saving without `--project` / `--global` uses the project file when `.min-agent/` exists.
+In chat, `/memory on` or `/memory off` toggles it; `/memory` lists notes; `/memory some text` saves one.
 
-`pricing` 覆盖模型价格（USD / 1M tokens），用于成本估算；未配置时自动从 models.dev 获取。
+## Configuration
 
-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.
+Run `min-agent setup` for a guided setup — this is the easiest way to add or switch AI providers.
 
-`contextWindow` 填写该模型的上下文长度（token）。自定义接口请按实际容量填写，例如 100 万填 `1000000`。未填写时会向接口查询；查不到时按 512k 处理。旧的工具输出会自动省略，避免占满上下文。
+Settings live in `~/.min-agent/config.json` (global). A project can have its own `.min-agent/config.json` that only applies there.
 
-`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).
+## Extending It
 
-A run continues in one model pass until the model finishes, the context fills (~75% of the window), the reply comes back empty, or a tool-only turn has no final answer. Context overflow and empty turns auto-continue up to `agent.maxContinues` times (default 40). Set `agent.autoContinue` to `false` to stop and wait for the next message (web research that has not yet produced the requested file or answer still continues, and further search/fetch calls return a notice to write from what is already known). If `agent.autoContinue` is omitted, `compaction.autoContinue` is used (default true). Optional `agent.maxSteps` is a hard tool-step ceiling for one pass (unset means no ceiling). When the provider answers with an empty stream (HTTP 200 and no content at all — usually an upstream timeout), the same request is re-sent up to `agent.maxEmptyAttempts` times (default 4; first retry immediate, then exponential backoff from `agent.emptyRetryDelayMs`, default 1000 ms) regardless of `autoContinue`, and the run then reports that the provider returned nothing instead of a vague "incomplete". Task lists and the original request are stored with the session and survive compaction. Repeated identical tool calls are stopped. Long stretches of web search/fetch without producing the requested output are redirected to finish the work; further search/fetch calls then return that same notice instead of new results.
+- **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.
 
-A turn also has a time / step budget (`agent.turnTimeLimitMs`, default 20 min; `agent.softStepLimit`, default 120 tool steps). When it runs out the model is asked once to wrap up and summarise, then the turn stops — a finished answer is never overridden by the budget. Model requests are guarded by a first-byte timeout (`agent.requestTimeoutMs`, default 180 s) and a stream idle timeout (`agent.streamIdleTimeoutMs`, default 90 s); a stalled request is aborted and retried like an empty reply. Old tool payloads are only trimmed once the context is filling up (60% of the window), biggest first, and each stub keeps the path of the full output on disk so the model can read it again. Sessions are written incrementally during a run, so a crash keeps the work done so far. `bash` commands are killed after `tools.bashTimeoutMs` (default 10 min) unless the call sets its own timeout. Sub-agents (`task`, `explore`) share the parent's research and cost budget; their step ceilings are `agent.subAgentMaxSteps` / `agent.exploreMaxSteps`.
+## API Access
 
-Research is judged by what it returns: rounds that bring new URLs or domains are free (up to `agent.researchTotalCap`, default 24 calls per turn), while `agent.researchSteerAfter` (default 3) rounds without a new source steer the model to write, and `agent.researchStopAfter` (default 5) removes `search_web` / `web_fetch` for the rest of the turn.
+`min-agent serve` starts a local HTTP API server so other apps can talk to min-agent. Reference: [docs/API.md](docs/API.md)
 
-Provider types: `openai-compatible` | `openai` | `ollama`
+## License
 
-Logs: `~/.min-agent/logs/min-agent.YYYY-MM-DD.log` (rotated daily, kept 7 days). Lines inside a run carry `[run=<id> pass=<n>]`. Set `MIN_AGENT_TRACE=1` to also log a summary of every model request and response (model, message/tool counts, status, time to first byte).
+MIT
 
-Input history: `~/.min-agent/input-history.json` (up to 1000 entries)
+<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]`。
-
-Connected servers expose resources and prompts to the agent via `mcp_list_resources` / `mcp_read_resource` / `mcp_list_prompts` / `mcp_get_prompt`. `/mcp` shows counts when a server advertises them.
-
-远程服务器如需 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 user path overrides the earlier one; within one path the top-level `SKILL.md` wins over a nested copy.
-- Built-in skills shipped with min-agent (including `self-config`, which the agent loads automatically when changing its own settings) are always discovered and win on name over user copies.
-- `MIN_AGENT_SKILLS_DIRS` (path-delimiter separated) replaces the user discovery list; built-in skills still load unless `MIN_AGENT_NO_BUILTIN_SKILLS=1`.
-- 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` | 切换"计划模式"（只看不改） |
+| `/think` | 选择思考强度 |
+| `/memory` | 开关记忆，或保存一条 |
+| `/undo` | 撤销上一轮操作 |
+| `/diff` | 查看当前已产生的文件改动 |
+| `/sessions` | 查看或切换会话 |
+| `/attach <路径>` | 附加本地图片 |
+| `/mcp` | 查看已连接的 MCP 服务 |
+| `/skills` | 管理技能 |
+| `/tokens` | 查看用量与预估费用 |
+| `/help` | 查看全部命令 |
+| `/exit` | 退出 |
 
-## Plugins
+快捷键：**Ctrl+C** 清空输入框（连按两次退出）· **Ctrl+V** 粘贴图片 · 多行粘贴会收成片段 · **Ctrl+B** 选中文本以复制 · 也支持鼠标拖拽选中并自动复制 · 点击工具或思考块可展开或收起。
 
-Custom tools: `.min-agent/tools/*.ts` or `~/.min-agent/tools/*.ts`
+## 掌控风险
 
-By default a custom tool asks before it runs. Set `readOnly: true` (or `dangerous: false`) to skip the prompt. Plan mode only keeps `readOnly` custom tools.
+min-agent 默认会在执行有风险的操作前先询问你。
 
-```typescript
-export const myTool = {
-  description: "...",
-  parameters: { arg: { type: "string", description: "..." } },
-  execute: async ({ arg }) => "result"
-}
+```bash
+min-agent permission                 # 查看当前设置
+min-agent --permission ask           # 有风险操作前先询问（默认）
+min-agent --permission accept-edits  # 仅自动批准文件修改
+min-agent --permission allow-all     # 自动批准所有操作 —— 请谨慎使用
 ```
 
-```typescript
-export const dockerPs = {
-  description: "List running docker containers",
-  readOnly: true,
-  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 sandbox            # 查看当前限制级别
+min-agent sandbox off        # 不限制（默认）
+min-agent sandbox workspace  # 仅允许修改当前项目文件夹内的内容
 ```
 
----
+## 记忆
 
-## HTTP API
+跨会话记忆默认关闭。需要记住偏好或项目约定时再打开：
 
 ```bash
-min-agent serve [--port 8787]
+min-agent memory                 # 查看开关与已保存内容
+min-agent memory on              # 开启记忆（写入配置）
+min-agent --memory on            # 同上；若同时带消息则只对本轮生效
+min-agent memory add "prefer bun"
 ```
 
-Full reference: [docs/API.md](docs/API.md)
+对话里用 `/memory on` 或 `/memory off` 开关；`/memory` 查看；`/memory 一段话` 保存一条。
 
----
+## 配置
+
+运行 `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` | Optional Serper key override for `search_web` (takes precedence over `serperApiKey` in config; a built-in default is used otherwise) |
-| `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 user skill discovery list (built-in skills still load) |
-| `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` to skip skills shipped with min-agent |
-| `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