min-agent 3.27.2610261702 → 3.29.2610270016

package/README.md

@@ -37,33 +37,41 @@
 npm install -g min-agent
 min-agent setup       # pick a provider and model (interactive)
 min-agent             # start chatting
-min-agent models      # list the models your provider offers
 ```
 
-`min` is available as a shorter alias with identical functionality (`min "..."`, `min serve`, ...).
+`min` is a shorter alias with identical functionality (`min "..."`, `min serve`, ...).
+
+## What You Can Do
+
+- **Work on real code** — the agent reads your files, edits them, runs commands, and checks its own work.
+- **Ask the web** — ask mode answers questions with live search, no file access.
+- **Plan before touching anything** — plan mode lets the agent look around without changing a thing.
+- **Stay in one conversation** — sessions are saved automatically and can be resumed at any time.
+- **Keep your preferences** — optional memory lets the agent carry notes across sessions.
+- **Work on your phone or in a browser** — a built-in web UI covers the same features as the terminal.
 
 ## Usage
 
 ```bash
-min-agent "your message"        # start a session and send a message (agent mode)
-min-agent ask "your question"   # start in ask mode — web Q&A & search only
+min-agent "your message"        # start a session and send a message
+min-agent ask "your question"   # start in ask mode — web Q&A and search only
 min-agent exec "your message"   # one-shot question, then exit (--quiet/--json for scripts)
-min-agent push                  # lightweight shortcut: stage, commit and push (no MCP/skills/rules/memory, no session saved)
-min-agent commit                # lightweight shortcut: stage and commit, no push
-min-agent git                  # interactive: provider → model → thinking for commit/push (independent of agent config)
-min-agent light                # interactive: switch → provider → model → thinking; `light off` pauses it
+min-agent push                  # quick shortcut: stage, commit and push
+min-agent commit                # quick shortcut: stage and commit, no push
+min-agent git                   # choose which model handles commit/push, separately from chat
 min-agent --resume <id>         # resume a previous session (a unique id prefix is enough)
 min-agent --continue            # resume the most recent session
-min-agent sessions              # list saved sessions (-n 50 shows the latest 50, --all shows every entry, --json for scripts)
+min-agent sessions              # list saved sessions (-n 50, --all, --json)
+min-agent models                # list the models your provider offers
 min-agent models --provider x   # list models for a specific provider
 min-agent help [command]        # show help for the root or any subcommand
-min-agent scope global          # share one history across projects (default: per working directory)
+min-agent scope global          # share one history across projects (default: per folder)
 min-agent -i photo.png "..."    # attach an image
 min-agent -m gpt-5.5 "..."      # pick a model for one message
 min-agent --provider anthropic "..."   # pick a provider for one message
 ```
 
-Modes: **agent** (default) is the full coding agent — read/write files, run commands, manage config. **ask** is a separate web-Q&A mode with its own system prompt — only live search (`search_web` / `web_fetch`); it skips MCP, skills, rules, and memory. Use `/ask` / `/agent` in chat to switch (add `--project` to keep the choice local to this project). The choice is remembered: `min-agent ask`, or `/ask` in a session, means the next plain `min-agent` also starts in ask mode.
+**Agent mode** (default) is the full coding assistant. **Ask mode** only answers questions from the web and touches nothing on disk. Switch with `/ask` / `/agent` in chat (add `--project` to keep the choice local to this project) — the choice is remembered for the next start.
 
 ## While Chatting
 
@@ -72,36 +80,28 @@ Type `/` to open the command menu; **↑/↓** selects. On an empty input, **↑
 | Command | What it does |
 |---|---|
 | `/new` · `/sessions` | New session · switch between sessions (`--global` shows global history) |
-| `/scope` | Where history is saved: per working directory (default) or global |
+| `/scope` | Where history is saved: per folder (default) or shared globally |
 | `/model` · `/models` · `/provider` | Current provider's models · every provider's models · switch provider |
 | `/ask` · `/agent` | Switch to ask (web Q&A) / agent (coding) mode |
 | `/plan` | Plan mode — look, don't touch |
-| `/think` · `/ctx` | Thinking intensity · local-model context window |
+| `/think` · `/ctx` | Thinking intensity · context window for local models |
 | `/memory` | Toggle memory or save a note |
-| `/light` | Pick the lighter model: switch, provider, model, then thinking |
+| `/light` | Pick a lighter model for background work |
 | `/undo` · `/diff` | Undo last turn · show changes so far |
 | `/queue` | List, drop or clear messages waiting behind the running turn |
 | `/attach` · `/mcp` · `/skills` | Attach an image · MCP servers · skills |
-| `/tokens` · `/help` | Usage, reuse & cost · all commands |
+| `/tokens` · `/help` | Usage and cost · all commands |
 | `/exit` · `/quit` | Exit (also `/q`) |
 
-The input box stays live while the agent works: press Enter and the message joins a queue that runs in order once the current turn ends (the status bar and spinner show the backlog). Use `/queue` to inspect it, `/queue rm <n>` to pull one out, `/queue clear` to drop them all; Esc cancels the running turn and drops the queue. Slash commands never enter that queue. A reply that degenerates into repeating the same block of text is cut off automatically, with a notice, and the repetition is not saved to the history. If a change already passed its check but the agent keeps building scratch harnesses or re-verifying it, it is nudged once to wrap up and then stopped, rather than spinning for hours.
-
-Commands that only read state or write config — `/permission`, `/sandbox`, `/memory`, `/plan`, `/ask`, `/agent`, `/reload`, `/rename`, and the picker commands given an argument (`/model <id>`, `/think low`, `/light off`, `/ctx 8k`, …) — run immediately even mid-turn, so a permission change applies to the very next tool call instead of waiting behind the whole turn. Commands that would mutate the conversation or open an overlay (`/undo`, `/new`, `/compact`, `/model`, `/light`, `/models`, …) are refused mid-turn with a notice; they never queue as a user message.
-
-Shortcuts: **Ctrl+C** clears input (press twice to exit) · **Shift+Enter** / **Ctrl+J** inserts a newline · **Ctrl+V** pastes an image · **Ctrl+B** copies selected text · **Ctrl+O** expands the tool or thinking row in view · click a tool or thinking block to expand it.
-
-When the agent asks several questions at once they share one panel: a tab strip at the top shows progress (✓ = answered), **Enter** answers the current question and jumps to the next unanswered one, **Tab** / **Shift+Tab** switch between questions (drafts are kept), and the final 提交 page lists every answer — Enter submits them all (unanswered ones count as skipped), **Esc** cancels the whole set. Long prompts and option lists scroll inside the panel instead of filling the screen. In `exec` the questions are asked one after another; type option numbers (`1,3` for multi-select) or leave a line empty to skip. The Web UI shows the same set as one card with a step per question and a summary step that submits everything together.
+The input box stays live while the agent works: press Enter and your message joins a queue that runs once the current turn ends. Use `/queue` to inspect it, `/queue rm <n>` to pull one out, `/queue clear` to drop them all; **Esc** cancels the running turn. Commands that only read state or change a setting (`/permission`, `/memory`, `/plan`, `/model <id>`, ...) apply immediately, even mid-turn.
 
-## Updates
+**Shortcuts:** **Ctrl+C** clears input (press twice to exit) · **Shift+Enter** / **Ctrl+J** inserts a newline · **Ctrl+V** pastes an image · **Ctrl+B** copies selected text · **Ctrl+O** expands the tool or thinking row in view · click a tool or thinking block to expand it.
 
-min-agent checks for new versions at startup in the background (at most once a day, never blocking the session). When one is found you'll see a notice in the chat and the new version is installed in the background via `npm install -g min-agent`; it takes effect the next time you start min-agent. Upgrade failures are silent. Skip the check with `MIN_AGENT_NO_AUTO_UPDATE=1`; check or upgrade manually with `min-agent update [--check]`.
+When the agent asks several questions at once they share one panel: **Enter** answers and jumps to the next unanswered question, **Tab** / **Shift+Tab** switch between them, and the last page submits every answer. **Esc** cancels the whole set. Long question and option lists scroll inside the panel.
 
 ## Staying in Control
 
-File edits are auto-approved by default; risky actions always ask. When several actions in one step need approval, they're combined into a single prompt instead of a stack of separate ones. Each prompt offers 允许 / 总是允许 / 拒绝 — choosing 总是允许 remembers that action for the current session, so repeated identical commands or MCP tools won't ask again.
-
-`min-agent exec` (one-shot) runs more freely by default: edits and ordinary commands don't ask — only genuinely destructive commands (deleting files, dropping/truncating databases, disk-wiping, `git reset --hard`, etc.) still prompt. Pass `--permission` or `--yes` to override. Thinking and tool calls print as a single summary line each.
+File edits are auto-approved by default; risky actions always ask. When several actions need approval at once, you get a single prompt listing all of them instead of a stack of separate ones. Each prompt offers 允许 / 总是允许 / 拒绝 — choosing 总是允许 remembers that action for the current session, so repeated commands or tools won't ask again.
 
 ```bash
 min-agent permission                 # show current setting
@@ -111,54 +111,69 @@ min-agent --permission allow-all     # auto-approve everything — use with care
 min-agent sandbox workspace          # only allow changes inside this folder
 ```
 
-In `workspace` / `strict`, temp dirs, package-manager caches and min-agent's own `~/.min-agent` (config, skills, memory, MCP) stay writable, so the agent can still configure itself. `strict` additionally stops shell commands (via seatbelt / bwrap) from reading the rest of your home directory: only the workspace, its enclosing git repo, `~/.min-agent`, caches and toolchains (`~/.nvm`, `~/.bun`, `~/.cargo`, `~/.gitconfig` …) stay readable; system directories are unaffected. Credential paths such as `~/.ssh`, `~/.aws` and `~/.netrc` are blocked in every mode.
+With the sandbox on, the agent can still read and write its own settings and caches, so it can configure itself. The strictest level also stops shell commands from reading the rest of your home directory. Credential files such as `~/.ssh`, `~/.aws` and `~/.netrc` are blocked at every level. On Windows, shell-level isolation isn't available: the strictest level refuses to run shell commands, while the folder level still blocks file changes outside the workspace.
 
-On Windows, OS-level command isolation (macOS seatbelt / Linux bwrap) is unavailable: `strict` refuses shell commands; `workspace` still blocks file tools outside the folder. Shell commands prefer Git Bash when installed.
+## Memory
 
 Off by default. Turn it on to keep facts across sessions:
 
 ```bash
-min-agent memory on             # enable (writes config)
+min-agent memory on             # enable
 min-agent memory add "prefer bun"
 ```
 
-In chat: `/memory on|off` toggles, `/memory` lists notes, `/memory some text` saves one.
+In chat: `/memory on|off` toggles it, `/memory` lists notes, `/memory some text` saves one.
 
 ## Configuration
 
-min-agent reads your providers from `~/.min-agent/config.json`. Run `min-agent setup` to add one:
+min-agent ships without any keys — the first run walks you through setup:
 
 ```bash
-min-agent setup        # add a provider (interactive; type to search APIs, coding plans, or a custom URL)
-min-agent provider     # show the active provider and any you've added
+min-agent setup        # add a provider and model (interactive; type to search)
+min-agent provider     # show the active provider and the ones you've added
 min-agent models       # list the models your provider offers
 ```
 
-`min-agent provider <name>` switches the active provider (add/edit/remove go through `min-agent setup`).
+`min-agent provider <name>` switches the active provider. Settings are stored in your own config folder and can be set globally or per project; nothing is written inside your project directory.
+
+`min-agent settings` prints every active setting in one screen — the value and where it comes from (default, global, project, environment, or this run).
 
-Adding an OpenCode Go / OpenCode Zen endpoint (e.g. `https://opencode.ai/zen/go/v1`) is detected during setup. The wizard turns the session id on by default (you can turn it off); every request then carries the `x-opencode-session` header that endpoint requires — one stable id per conversation. Use `--opencode-session` / `--no-opencode-session` to force it on or off (e.g. for a gateway that proxies OpenCode Go under another host).
+An optional lighter model handles background chores: shortening long conversations, naming sessions, tidying long search results, and filing memory notes. Leave it empty to keep using the current model. `min-agent light` walks through the choices, `/light` does the same in chat, and `min-agent light off` pauses it without losing the selection.
 
-Providers are plain JSON in `~/.min-agent/config.json` — nothing is hidden, and every key stays where you put it.
+Conversation history is saved per folder by default. To share one history across all projects, run `min-agent scope global` (or `/scope global`); `min-agent scope` shows the current setting.
+
+## Extending It
 
-Settings live in `~/.min-agent/config.json` (global). Per-project settings go to `~/.min-agent/sessions/<project-key>/config.json` (auto-created; nothing is written inside the project directory).
+- **MCP servers** — connect external tools and data sources: `min-agent mcp -h`
+- **Skills** — reusable instructions the agent loads when they're relevant: `min-agent skills -h`
+- **Project rules** — add `AGENTS.md` or `RULES.md` to your project so the agent follows your conventions; global rules live in `~/.min-agent/rules.md`
 
-`min-agent settings` prints every active setting in one screen — value, where it comes from (default / global / project / env / this run) and which file to edit.
+## Web UI
 
-Each running instance reads config into memory at startup (and again on `/new`, `/resume`, or a serve working-directory switch). Edits from another instance — or from another terminal's CLI — do not affect a running conversation; they apply when the session restarts or a new session starts. The instance's own settings changes still apply immediately.
+```bash
+min-agent web
+```
 
-An optional lighter model (`light.model`, provider optional) shortens long conversations, names the session, tidies long search results, and files notes when memory is on. Leave it empty to keep using the current model. In a terminal, `min-agent light` walks through the switch, provider, model, then thinking intensity; without a terminal it prints the current setting. `min-agent light off` turns it off and keeps the saved model; `min-agent light on` turns it back on. Leave thinking unset to keep it off. In chat, `/light` opens the same picker; `/light on` and `/light off` still change the switch directly.
+Starts a local web app (default <http://127.0.0.1:8787>) — open it in a browser and start chatting, no extra setup.
 
-Conversation history is saved per working directory by default, in `~/.min-agent/sessions/<project-key>/sessions/` — still inside the global config dir, never in the project. To share one history across projects, run `min-agent scope global` (or `/scope global`); `min-agent scope` shows the current setting.
+- Streaming replies, thinking and tool calls, image paste/upload
+- Switch between agent and ask mode, and between project folders
+- Session list with rename, delete, undo and compress; `⌘K` / `Ctrl+K` command palette
+- Edit your last message and send it again; failed messages stay in the conversation for a retry
+- A settings page that covers everything the CLI does — providers, models, skills, MCP servers, memory, rules, thinking intensity, confirmation and sandbox
+- Light and dark themes, mobile friendly
 
-## Extending It
+`--host` / `--port` work the same as for `min-agent serve`. To run it in the background:
 
-- **MCP servers** — connect external tools: `min-agent mcp -h`
-- **Skills** — reusable instructions the agent loads on demand: `min-agent skills -h`
-- **Project rules** — add `AGENTS.md` or `RULES.md` to your project; global rules go in `~/.min-agent/rules.md` or `~/.min-agent/AGENTS.md`
+```bash
+min-agent web -d       # run in the background (log: ~/.min-agent/serve.log)
+min-agent web --status # check background status
+min-agent web --stop   # stop the background service
+```
 
 ## API Access
 
-`min-agent serve` starts a local HTTP API for other apps to talk to. Reference: [docs/API.md](docs/API.md)
+`min-agent serve` starts a local HTTP API so other apps can talk to min-agent.
 
 ## License
 
@@ -184,71 +199,71 @@ MIT
 npm install -g min-agent
 min-agent setup       # 选择服务商与模型（交互式）
 min-agent             # 开始对话
-min-agent models      # 查看当前服务商可用的模型
 ```
 
 `min` 是等价的短命令，功能完全相同（`min "..."`、`min serve` 等）。
 
+## 它能帮你做什么
+
+- **动手改代码**——读取、修改你的文件，执行命令，并自己检查结果
+- **联网问答**——ask 模式只查资料、回答问题，不碰你的文件
+- **先想清楚再动手**——计划模式可以查看项目但不会做任何修改
+- **对话随时接着聊**——会话自动保存，随时恢复
+- **记住你的习惯**——可选的记忆功能让偏好跨会话保留
+- **也可以用浏览器**——内置网页版，手机上也能用
+
 ## 基本用法
 
 ```bash
-min-agent "你的消息"            # 进入交互会话并立即发送消息（agent 模式）
+min-agent "你的消息"            # 进入会话并立即发送消息
 min-agent ask "你的问题"        # 以 ask 模式进入——仅联网问答与搜索
 min-agent exec "你的消息"       # 单次提问后自动退出（--quiet / --json 适合脚本）
-min-agent push                  # 轻量快捷指令：暂存提交并推送当前分支（跳过 MCP/技能/规则/记忆，不保存会话）
-min-agent commit                # 轻量快捷指令：暂存并提交，不推送
-min-agent git                  # 交互式选择 commit/push 的 服务商 → 模型 → 思考强度（不受 agent 配置影响）
-min-agent light                # 交互式选择轻量模型：开关 → 服务商 → 模型 → 思考强度
-min-agent --resume <id>        # 恢复之前的会话（输入唯一的 id 前缀即可）
-min-agent --continue           # 继续最近一次会话
-min-agent sessions             # 查看已保存的会话（-n 50 显示最近 50 条，--all 显示全部，--json 机器可读输出）
-min-agent models --provider x  # 查看指定服务商的模型列表
-min-agent help [命令]          # 查看根命令或任意子命令的帮助
-min-agent scope global         # 所有项目共用一个历史（默认按工作目录分别保存）
-min-agent -i photo.png "..."   # 为一条消息附带图片
-min-agent -m gpt-5.5 "..."     # 为一条消息指定模型
+min-agent push                  # 快捷指令：暂存、提交并推送当前分支
+min-agent commit                # 快捷指令：暂存并提交，不推送
+min-agent git                   # 单独为提交/推送选择服务商与模型
+min-agent --resume <id>         # 恢复之前的会话（输入唯一的 id 前缀即可）
+min-agent --continue            # 继续最近一次会话
+min-agent sessions              # 查看已保存的会话（-n 50、--all、--json）
+min-agent models                # 查看当前服务商可用的模型
+min-agent models --provider x   # 查看指定服务商的模型列表
+min-agent help [命令]           # 查看根命令或任意子命令的帮助
+min-agent scope global          # 所有项目共用一份历史（默认按文件夹保存）
+min-agent -i photo.png "..."    # 为一条消息附带图片
+min-agent -m gpt-5.5 "..."      # 为一条消息指定模型
 min-agent --provider anthropic "..."   # 为一条消息指定服务商
 ```
 
-会话模式：**agent**（默认）是完整编码智能体——读写文件、执行命令、管理配置；**ask** 是独立的联网问答模式，使用专门的系统提示词，仅保留联网搜索（`search_web` / `web_fetch`），不加载 MCP、skills、规则与记忆。对话中用 `/ask` / `/agent` 随时切换（加 `--project` 只对当前项目生效）。切换会被记住：`min-agent ask` 或在会话里 `/ask` 之后，下次直接运行 `min-agent` 也以 ask 模式启动。
+**agent 模式**（默认）是完整的编程助手；**ask 模式**只联网回答，不会改动任何文件。对话中用 `/ask` / `/agent` 切换（加 `--project` 只对当前项目生效），下次启动会沿用你的选择。
 
 ## 对话中的操作
 
-输入 `/` 弹出命令菜单，用 **↑/↓** 移动高亮；输入框为空时，**↑/↓** 翻看之前消息。
+输入 `/` 弹出命令菜单，用 **↑/↓** 移动高亮；输入框为空时，**↑/↓** 翻看之前的消息。
 
 | 命令 | 作用 |
 |---|---|
 | `/new` · `/sessions` | 新建会话 · 切换会话（`--global` 查看全局历史） |
-| `/scope` | 对话历史保存位置：按工作目录（默认）或全局共用 |
+| `/scope` | 对话历史保存位置：按文件夹（默认）或全局共用 |
 | `/model` · `/models` · `/provider` | 当前服务商的模型 · 全部服务商的模型 · 切换服务商 |
-| `/ask` · `/agent` | 切换 ask（联网问答）/ agent（编码）会话模式 |
+| `/ask` · `/agent` | 切换 ask（联网问答）/ agent（编程）模式 |
 | `/plan` | 计划模式——只看不改 |
-| `/think` · `/ctx` | 思考强度 · 本地模型上下文窗口 |
+| `/think` · `/ctx` | 思考强度 · 本地模型的上下文窗口 |
 | `/memory` | 开关记忆，或保存一条 |
-| `/light` | 逐步选择轻量模型：开关、服务商、模型、思考强度 |
+| `/light` | 为后台杂务选择一个更轻量的模型 |
 | `/undo` · `/diff` | 撤销上一轮 · 查看已产生的改动 |
 | `/queue` | 查看、移出或清空排在当前任务后面的消息 |
 | `/attach` · `/mcp` · `/skills` | 附加图片 · MCP 服务 · 技能 |
-| `/tokens` · `/help` | 用量、复用与费用 · 全部命令 |
+| `/tokens` · `/help` | 用量与费用 · 全部命令 |
 | `/exit` · `/quit` | 退出（`/q` 同） |
 
-任务执行时输入框依然可用：按 Enter 会把消息排进队列，当前任务结束后按顺序执行（运行提示行显示排队数量）。`/queue` 查看队列，`/queue rm <序号>` 移出一条，`/queue clear` 全部清空；Esc 取消当前任务，并丢弃排队消息。斜杠命令不会进入消息队列。模型输出陷入重复循环（同一段文字连续重复）时会自动截断本轮并提示，重复内容不会写入历史。改动已通过检查后若仍在反复搭临时脚本/重复验证，会先提醒一次收尾，仍未停止则结束本轮，避免长时间空转。
-
-只读取状态或只写配置的命令——`/permission`、`/sandbox`、`/memory`、`/plan`、`/ask`、`/agent`、`/reload`、`/rename`，以及带参数的选择类命令（`/model <id>`、`/think low`、`/light off`、`/ctx 8k` 等）——在任务执行中也会立即执行：改完确认模式马上对下一次工具调用生效，不必等整轮结束。会改动对话内容或打开浮层的命令（`/undo`、`/new`、`/compact`、`/model`、`/light`、`/models` 等）在任务执行中会被拒绝并提示等本轮结束，不会作为用户消息排队。
+任务执行时输入框依然可用：按 Enter 会把消息排进队列，当前任务结束后按顺序执行。用 `/queue` 查看队列，`/queue rm <序号>` 移出一条，`/queue clear` 全部清空；**Esc** 取消当前任务。只读状态或只改设置的命令（`/permission`、`/memory`、`/plan`、`/model <id>` 等）在任务执行中也会立即生效。
 
-快捷键：**Ctrl+C** 清空输入（连按两次退出）· **Shift+Enter** / **Ctrl+J** 换行 · **Ctrl+V** 粘贴图片 · **Ctrl+B** 复制选中的文本 · **Ctrl+O** 展开视图中间的工具/思考行 · 点击工具或思考块可展开收起。
+**快捷键：** **Ctrl+C** 清空输入（连按两次退出）· **Shift+Enter** / **Ctrl+J** 换行 · **Ctrl+V** 粘贴图片 · **Ctrl+B** 复制选中的文本 · **Ctrl+O** 展开视图中间的工具/思考行 · 点击工具或思考块可展开收起。
 
-智能体一次提出多个问题时，会在同一个面板里分页显示：顶部标签栏显示进度（已答的带 ✓），**Enter** 回答当前题并跳到下一道未答的题，**Tab** / **Shift+Tab** 在题目之间切换（填了一半的内容会保留），最后一页「提交」汇总所有回答，按 Enter 一起提交（没答的题算跳过），**Esc** 取消整组。题目或选项太长时，面板内部可以滚动，不会把屏幕撑满。`exec` 模式下则按顺序逐题提问，可以输入编号（多选写成 `1,3`），留空表示跳过该题。Web 界面把整组问题放在一张卡片里分步作答，最后在「汇总」一步统一提交。
-
-## 更新
-
-启动时 min-agent 会在后台检查新版本（每天最多一次，不阻塞会话）。发现新版本会在会话里提示，并自动通过 `npm install -g min-agent` 后台升级，下次启动自然生效，升级失败静默忽略。设置 `MIN_AGENT_NO_AUTO_UPDATE=1` 可以关闭；也可以随时手动执行 `min-agent update`（加 `--check` 仅检查）。
+智能体一次提出多个问题时，会在同一个面板里分页显示：**Enter** 回答当前题并跳到下一道未答的题，**Tab** / **Shift+Tab** 在题目之间切换，最后一页统一提交所有回答（没答的算跳过），**Esc** 取消整组。题目或选项太长时，面板内部可以滚动，不会把屏幕撑满。
 
 ## 掌控风险
 
-文件修改默认自动批准，危险操作仍会询问；同一步里有多个操作需要授权时，会合并成一个弹窗逐条列出，而不是弹出一堆。弹窗提供 允许 / 总是允许 / 拒绝 三个选项——选「总是允许」会在本次会话内记住该操作，之后重复的相同命令或 MCP 工具不再询问。
-
-`min-agent exec`（单次执行）默认更放手：文件修改和普通命令都不询问，只有真正具破坏性的命令（删除文件、drop/truncate 数据库、抹盘、`git reset --hard` 等）才会询问。加 `--permission` 或 `--yes` 可覆盖此默认。思考过程和工具调用各占一行摘要，不展开全文。
+文件修改默认自动批准，危险操作仍会询问；同一步里有多个操作需要授权时会合并成一个弹窗逐条列出，而不是弹出一堆。弹窗提供 允许 / 总是允许 / 拒绝 三个选项——选「总是允许」会在本次会话内记住该操作，之后重复的相同命令或工具不再询问。
 
 ```bash
 min-agent permission                 # 查看当前设置
@@ -258,16 +273,14 @@ min-agent --permission allow-all     # 自动批准所有操作——请谨慎
 min-agent sandbox workspace          # 仅允许修改当前文件夹内内容
 ```
 
-`workspace` / `strict` 下，临时目录、包管理器缓存，以及 min-agent 自己的 `~/.min-agent`（配置、技能、记忆、MCP）仍可读写，智能体照样能改自己的配置。`strict` 还会（通过 seatbelt / bwrap）禁止 shell 命令读取 home 目录下的其他内容：只有工作区、所在的 git 仓库、`~/.min-agent`、缓存与工具链（`~/.nvm`、`~/.bun`、`~/.cargo`、`~/.gitconfig` 等）可读，系统目录不受影响；`~/.ssh`、`~/.aws`、`~/.netrc` 等凭据路径在任何模式下都不可访问。
-
-Windows 上没有 macOS/Linux 那种命令级隔离：`strict` 会拒绝执行 shell；`workspace` 仍会限制文件工具写到目录外。装了 Git Bash 时优先用它跑命令。
+开启沙箱后，智能体仍可读写自己的配置与缓存，因此照样能调整自身设置。最严格的级别还会禁止 shell 命令读取 home 目录下的其他内容；`~/.ssh`、`~/.aws`、`~/.netrc` 等凭据文件在任何级别下都不可访问。Windows 上没有命令级隔离：最严格的级别会拒绝执行 shell，文件夹级别仍会限制文件工具写到目录外。
 
 ## 记忆
 
 默认关闭。想让偏好跨会话保留时再打开：
 
 ```bash
-min-agent memory on             # 开启记忆（写入配置）
+min-agent memory on             # 开启记忆
 min-agent memory add "prefer bun"
 ```
 
@@ -275,41 +288,27 @@ min-agent memory add "prefer bun"
 
 ## 配置
 
-min-agent 不附带任何密钥，首次运行会引导你走 `min-agent setup`：
+min-agent 不附带任何密钥，首次运行会引导你完成设置：
 
 ```bash
-min-agent setup      # 添加服务商（交互式；输入文字可搜索接口、编程套餐，或自己填地址）
+min-agent setup      # 添加服务商与模型（交互式；输入文字可搜索）
 min-agent provider   # 查看当前服务商，以及你已添加的服务商
 min-agent models     # 查看当前服务商可用的模型
 ```
 
-`min-agent provider <name>` 切换当前服务商（增、删、改走 `min-agent setup`）。
-
-添加 OpenCode Go / OpenCode Zen 接口（如 `https://opencode.ai/zen/go/v1`）时会自动识别。向导里会话编号默认打开，也可以关掉；之后每次调用都会带上该接口要求的 `x-opencode-session` 头，同一会话固定一个 id。用 `--opencode-session` / `--no-opencode-session` 可强制开启或关闭（例如换了域名的自建网关）。
+`min-agent provider <name>` 切换当前服务商。配置保存在你自己的用户目录下，可以全局生效，也可以只对某个项目生效，不会往项目目录里写任何文件。
 
-服务商配置是 `~/.min-agent/config.json` 里的普通 JSON，没有隐藏行为，key 也只存在你放的那个文件里。
+`min-agent settings` 一屏列出所有生效设置——当前值，以及它来自哪里（默认、全局、项目、环境变量或本次运行）。
 
-配置保存在 `~/.min-agent/config.json`（全局生效）。项目级配置保存在 `~/.min-agent/sessions/<project-key>/config.json`（自动创建，不会在项目目录里生成任何文件），仅对该项目生效。
+还可以另外指定一个轻量模型，用来压缩较长的对话、给会话起标题、整理过长的搜索结果，以及整理要记住的内容。留空则这些事情仍使用当前模型。`min-agent light` 会逐步带你选择，对话里的 `/light` 效果相同；`min-agent light off` 可以暂停它而不丢失已选模型。
 
-`min-agent settings` 一屏列出所有生效设置——当前值、来源（默认 / 全局 / 项目 / 环境变量 / 本次运行）以及该改哪个文件。
-
-每个运行中的实例在启动时把配置读入内存（serve 切换工作目录时也会重新读取）。其他实例或另一个终端 CLI 对配置的修改不影响正在进行的对话，要等重启或手动重载（交互模式 `/reload`、serve 的 `POST /v1/chat/reload-instructions`）才生效，`/new` 与切换会话不会重新读取；实例自己的设置修改仍然立即生效。
-
-可以另外指定一个轻量模型（`light.model`，服务商可以不填）。它用来压缩较长的对话、给会话起标题、整理过长的搜索结果，以及在开启记忆后整理要记住的内容。留空则这些事情仍使用当前模型。在终端里运行 `min-agent light` 会先选择开关，再选择服务商、模型和思考强度；没有终端时只显示当前设置。`min-agent light off` 关掉开关并保留已选模型，`min-agent light on` 再打开。思考强度留空则关闭。对话里输入 `/light` 会打开同样的逐步选择；`/light on` 和 `/light off` 仍可以直接开关。
-
-对话历史默认按工作目录保存：`~/.min-agent/sessions/<project-key>/sessions/`，同样在全局配置目录下，不会写进项目目录。想让所有项目共用一个历史，执行 `min-agent scope global`（或对话中 `/scope global`）；`min-agent scope` 查看当前设置。
+对话历史默认按文件夹保存。想让所有项目共用一份历史，执行 `min-agent scope global`（或对话中 `/scope global`）；`min-agent scope` 查看当前设置。
 
 ## 扩展能力
 
 - **MCP 服务**：连接外部工具与数据源，`min-agent mcp -h`
-- **技能（Skills）**：由 agent 按需加载的可复用指令集，`min-agent skills -h`
-- **项目规则**：在项目里添加 `AGENTS.md` 或 `RULES.md`；全局规则写入 `~/.min-agent/rules.md` 或 `~/.min-agent/AGENTS.md`
-
-## API 接入
-
-`min-agent serve` 可启动本地 HTTP API 服务，供其他应用调用。完整说明见 [docs/API.md](docs/API.md)
-
-开启 CORS（`MIN_AGENT_SERVE_CORS=1`）且未设置 `MIN_AGENT_SERVE_TOKEN` 时，只接受本机来源的浏览器请求；`file://` 页面或 sandbox iframe 发出的 `Origin: null` 默认拒绝，需要时设 `MIN_AGENT_SERVE_ALLOW_NULL_ORIGIN=1`。
+- **技能（Skills）**：智能体在需要时自行加载的可复用指令，`min-agent skills -h`
+- **项目规则**：在项目里添加 `AGENTS.md` 或 `RULES.md`，让智能体遵循你的约定；全局规则放在 `~/.min-agent/rules.md`
 
 ## 网页版
 
@@ -317,27 +316,16 @@ min-agent models     # 查看当前服务商可用的模型
 min-agent web
 ```
 
-启动 HTTP API 并附带网页版对话助手（默认 <http://127.0.0.1:8787>），浏览器打开即用，无需 CORS 或令牌配置。网页版支持：
-
-- 流式对话、思考过程与工具调用展示、图片粘贴/上传
-- 会话模式切换：agent（完整编码智能体）/ ask（仅联网问答与搜索）
-- 工作目录切换：顶栏目录菜单直接切换项目目录（记住后下次启动自动进入）
-- 会话管理：历史列表、重命名、删除、撤销最后一轮、压缩历史。生成过程中离开当前会话会先确认。`⌘K` / `Ctrl+K` 打开命令面板，可搜索会话、切换模型或新开对话
-- 可以修改最后一条消息后重新发送。发送失败会留在对话里，可直接重试
-- 设置页（完整覆盖 CLI 配置，无需命令行即可修改）：
-  - 服务商：添加/编辑/删除/切换，含 API Key、类型与上下文窗口
-  - 模型：默认模型（全局/项目作用域）、本次会话模型、Ollama 上下文档位
-  - Skills：启用/禁用（全局/项目）、查看详情、新建、重新扫描、孤儿引用清理
-  - MCP：添加/编辑/删除、启用/禁用、连接状态与工具列表
-  - 记忆：开关、条目增删与搜索、全局/项目作用域
-  - 规则：全局与项目规则文件在线编辑，保存即刻生效
-  - 行为与隔离：思考强度、确认模式、沙箱级别/联网/目录白名单
-- 需要确认或回答时，在输入框上方直接操作。按 Esc 会先确认是否停止这一轮
-- 明暗主题、移动端适配
+启动本地网页版（默认 <http://127.0.0.1:8787>），浏览器打开即用，无需额外配置。
 
-`--host` / `--port` 与 `serve` 相同。产物缺失时先在仓库内执行 `bun run build:web`（npm 发布包已内置），或用 `MIN_AGENT_WEB_DIST` 指定产物目录。
+- 流式回复、思考过程与工具调用展示，图片可粘贴或上传
+- 在 agent（完整编程助手）与 ask（仅联网问答）之间切换，也能直接切换项目文件夹
+- 会话列表支持重命名、删除、撤销最后一轮与压缩历史；`⌘K` / `Ctrl+K` 打开命令面板
+- 可以修改最后一条消息后重新发送，发送失败的消息留在对话里可直接重试
+- 设置页覆盖命令行能做的全部配置：服务商、模型、技能、MCP 服务、记忆、规则、思考强度、确认方式与沙箱
+- 明暗主题，手机端适配
 
-后台运行与停止：
+`--host` / `--port` 与 `min-agent serve` 相同。后台运行与停止：
 
 ```bash
 min-agent web -d       # 后台运行（日志: ~/.min-agent/serve.log）
@@ -345,6 +333,10 @@ min-agent web --status # 查看后台服务运行状态
 min-agent web --stop   # 停止后台服务
 ```
 
+## API 接入
+
+`min-agent serve` 可启动本地 HTTP 服务，供其他应用（脚本、编辑器插件、自建界面）调用 min-agent。
+
 ## License
 
-MIT
+MIT