min-agent 0.6.1 → 0.6.3

package/README.md

@@ -4,6 +4,8 @@
 
 一款在终端里运行的 AI 编程助手 · An AI coding agent that lives in your terminal
 
+**🌐 [https://min-agent.lonae.com](https://min-agent.lonae.com)**
+
 [![English](https://img.shields.io/badge/lang-English-blue.svg)](#english)
 [![简体中文](https://img.shields.io/badge/lang-简体中文-red.svg)](#简体中文)
 
@@ -33,108 +35,83 @@
 
 ```bash
 npm install -g min-agent
-min-agent             # Start chatting (a built-in model is ready)
-min-agent setup       # Optional: add or switch your own AI provider
-```
-
-## Basic Usage
-
-```bash
-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
+min-agent             # start chatting (built-in OpenRouter model, preset & locked)
+min-agent models      # list models (always openrouter/free)
 ```
 
-Attach an image or pick a specific model/provider for one message:
+## Usage
 
 ```bash
-min-agent -i photo.png "what's in this image?"
-min-agent -m gpt-5.5 "your message"
-min-agent --provider anthropic "your message"
+min-agent "your message"        # start a session and send a message
+min-agent exec "your message"   # one-shot question, then exit
+min-agent --resume <id>         # resume a previous session
+min-agent history               # list saved sessions
+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
 ```
 
 ## While Chatting
 
-Type `/` to open a command menu; **↑ / ↓** moves the highlight. With an empty input, **↑ / ↓** recalls previous messages.
+Type `/` to open the command menu; **↑/↓** selects. On an empty input, **↑/↓** recalls past messages.
 
-| Command | Description |
+| Command | What it does |
 |---|---|
-| `/new` | Start a new session |
-| `/model` | Switch model |
-| `/provider` | Switch provider (interactive picker) |
-| `/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 |
-| `/mcp` | Show connected MCP servers |
-| `/skills` | Manage skills |
-| `/tokens` | Usage and estimated cost |
-| `/ctx` | Choose local-model context window |
-| `/help` | Show all commands |
-| `/exit` | Exit |
-
-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 · when it asks you to choose, use **↑/↓** and **Enter** (Space checks items in multi-select).
+| `/new` · `/sessions` | New session · switch between sessions |
+| `/model` · `/provider` | Switch model / provider |
+| `/plan` | Plan mode — look, don't touch |
+| `/think` · `/ctx` | Thinking intensity · local-model context window |
+| `/memory` | Toggle memory or save a note |
+| `/undo` · `/diff` | Undo last turn · show changes so far |
+| `/attach` · `/mcp` · `/skills` | Attach an image · MCP servers · skills |
+| `/tokens` · `/help` | Usage & cost · all commands |
 
-## Staying in Control
+Shortcuts: **Ctrl+C** clears input (press twice to exit) · **Ctrl+V** pastes an image · **Ctrl+B** copies selected text · click a tool or thinking block to expand it.
 
-min-agent asks for confirmation before risky actions by default. File edits are auto-approved unless you change this.
-
-```bash
-min-agent permission                 # Show current setting
-min-agent --permission ask           # Confirm before risky actions
-min-agent --permission accept-edits  # Auto-approve file edits only (default)
-min-agent --permission allow-all     # Auto-approve everything — use with care
-```
+## Staying in Control
 
-You can also limit what it's allowed to touch on your machine:
+File edits are auto-approved by default; risky actions always ask.
 
 ```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
+min-agent permission                 # show current setting
+min-agent --permission ask           # confirm before risky actions
+min-agent --permission accept-edits  # auto-approve file edits (default)
+min-agent --permission allow-all     # auto-approve everything — use with care
+min-agent sandbox workspace          # only allow changes inside this folder
 ```
 
 ## Memory
 
-Remembered notes are off by default. Turn them on when you want facts to persist across sessions:
+Off by default. Turn it on to keep facts across sessions:
 
 ```bash
-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 on             # enable (writes config)
 min-agent memory add "prefer bun"
 ```
 
-In chat, `/memory on` or `/memory off` toggles it; `/memory` lists notes; `/memory some text` saves one.
+In chat: `/memory on|off` toggles, `/memory` lists notes, `/memory some text` saves one.
 
 ## Configuration
 
-Run `min-agent setup` to add or switch AI providers. If you skip it, min-agent uses a built-in OpenRouter model (`openrouter/free`). Your own providers in `~/.min-agent/config.json` always take over.
+No setup needed — the built-in OpenRouter provider (`openrouter/free`) is preset and locked:
 
 ```bash
-min-agent setup --type ollama
-min-agent setup --type openai-compatible --url https://api.example.com/v1 --api-key "$KEY" --name groq --default-model llama-3.1-70b
-min-agent setup --switch ollama
+min-agent models    # always lists exactly: openrouter/free
 ```
 
-Settings live in `~/.min-agent/config.json` (global). A project can have its own `.min-agent/config.json` that only applies there — run `min-agent init` to create it (min-agent never creates it on its own).
+The preset provider cannot be modified and `min-agent setup` refuses to add, edit, switch, or remove providers while it is active; the model is fixed to `openrouter/free` (no model list is fetched). Set `MIN_AGENT_NO_BUILTIN_PROVIDER=1` to disable the preset before configuring your own provider.
+
+Settings live in `~/.min-agent/config.json` (global). For per-project settings, run `min-agent init` to create `.min-agent/config.json`.
 
 ## Extending It
 
-- **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.
+- **MCP servers** — connect external tools: `min-agent mcp -h`
+- **Skills** — reusable instructions loaded automatically: `min-agent skills -h`
+- **Project rules** — add `AGENTS.md` or `RULES.md` to your project; global rules go in `~/.min-agent/rules.md`
 
 ## API Access
 
-`min-agent serve` starts a local HTTP API server so other apps can talk to min-agent. Reference: [docs/API.md](docs/API.md)
+`min-agent serve` starts a local HTTP API for other apps to talk to. Reference: [docs/API.md](docs/API.md)
 
 ## License
 
@@ -158,104 +135,79 @@ MIT
 
 ```bash
 npm install -g min-agent
-min-agent             # 开始对话（已内置可用模型）
-min-agent setup       # 可选：添加或切换你自己的 AI 服务商
+min-agent             # 开始对话（内置 OpenRouter 模型，已预设并锁定）
+min-agent models      # 查看模型（始终为 openrouter/free）
 ```
 
 ## 基本用法
 
 ```bash
-min-agent                       # 进入交互会话
-min-agent "你的消息"              # 进入交互会话并立即发送消息
-min-agent exec "你的消息"         # 单次提问后自动退出
-min-agent --resume <id>         # 恢复之前的会话
-min-agent history                # 查看已保存的会话
-min-agent models                 # 查看可用模型
-min-agent update                 # 升级到最新版本
-```
-
-为单条消息附带图片，或指定模型/服务商：
-
-```bash
-min-agent -i photo.png "这张图片是什么？"
-min-agent -m gpt-5.5 "你的消息"
-min-agent --provider anthropic "你的消息"
+min-agent "你的消息"            # 进入交互会话并立即发送消息
+min-agent exec "你的消息"       # 单次提问后自动退出
+min-agent --resume <id>        # 恢复之前的会话
+min-agent history              # 查看已保存的会话
+min-agent -i photo.png "..."   # 为一条消息附带图片
+min-agent -m gpt-5.5 "..."     # 为一条消息指定模型
+min-agent --provider anthropic "..."   # 为一条消息指定服务商
 ```
 
 ## 对话中的操作
 
-输入 `/` 弹出命令菜单，用 **↑ / ↓** 移动高亮。输入框为空时，**↑ / ↓** 翻看之前的消息。
+输入 `/` 弹出命令菜单，用 **↑/↓** 移动高亮；输入框为空时，**↑/↓** 翻看之前消息。
 
-| 命令 | 说明 |
+| 命令 | 作用 |
 |---|---|
-| `/new` | 开始新会话 |
-| `/model` | 切换模型 |
-| `/provider` | 交互式切换服务商 |
-| `/plan` | 切换"计划模式"（只看不改） |
-| `/think` | 选择思考强度 |
+| `/new` · `/sessions` | 新建会话 · 切换会话 |
+| `/model` · `/provider` | 切换模型 / 服务商 |
+| `/plan` | 计划模式——只看不改 |
+| `/think` · `/ctx` | 思考强度 · 本地模型上下文窗口 |
 | `/memory` | 开关记忆，或保存一条 |
-| `/undo` | 撤销上一轮操作 |
-| `/diff` | 查看当前已产生的文件改动 |
-| `/sessions` | 查看或切换会话 |
-| `/attach <路径>` | 附加本地图片 |
-| `/mcp` | 查看已连接的 MCP 服务 |
-| `/skills` | 管理技能 |
-| `/tokens` | 查看用量与预估费用 |
-| `/ctx` | 选择本地模型上下文窗口 |
-| `/help` | 查看全部命令 |
-| `/exit` | 退出 |
-
-快捷键：**Ctrl+C** 清空输入框（连按两次退出）· **Ctrl+V** 粘贴图片 · 多行粘贴会收成片段 · **Ctrl+B** 选中文本以复制 · 也支持鼠标拖拽选中并自动复制 · 点击工具或思考块可展开或收起 · 需要你做选择时用 **↑/↓** 移动、**Enter** 确认（多选时用空格勾选）。
+| `/undo` · `/diff` | 撤销上一轮 · 查看已产生的改动 |
+| `/attach` · `/mcp` · `/skills` | 附加图片 · MCP 服务 · 技能 |
+| `/tokens` · `/help` | 用量与费用 · 全部命令 |
+
+快捷键：**Ctrl+C** 清空输入（连按两次退出）· **Ctrl+V** 粘贴图片 · **Ctrl+B** 复制选中的文本 · 点击工具或思考块可展开收起。
 
 ## 掌控风险
 
-min-agent 默认自动批准文件修改，危险命令仍会询问。可按需调整：
+文件修改默认自动批准，危险操作仍会询问：
 
 ```bash
 min-agent permission                 # 查看当前设置
 min-agent --permission ask           # 有风险操作前先询问
 min-agent --permission accept-edits  # 仅自动批准文件修改（默认）
-min-agent --permission allow-all     # 自动批准所有操作 —— 请谨慎使用
-```
-
-也可以限制它能在你电脑上访问的范围：
-
-```bash
-min-agent sandbox            # 查看当前限制级别
-min-agent sandbox off        # 不限制（默认）
-min-agent sandbox workspace  # 仅允许修改当前项目文件夹内的内容
+min-agent --permission allow-all     # 自动批准所有操作——请谨慎使用
+min-agent sandbox workspace          # 仅允许修改当前文件夹内内容
 ```
 
 ## 记忆
 
-跨会话记忆默认关闭。需要记住偏好或项目约定时再打开：
+默认关闭。想让偏好跨会话保留时再打开：
 
 ```bash
-min-agent memory                 # 查看开关与已保存内容
-min-agent memory on              # 开启记忆（写入配置）
-min-agent --memory on            # 同上；若同时带消息则只对本轮生效
+min-agent memory on             # 开启记忆（写入配置）
 min-agent memory add "prefer bun"
 ```
 
-对话里用 `/memory on` 或 `/memory off` 开关；`/memory` 查看；`/memory 一段话` 保存一条。
+对话里用 `/memory on|off` 开关，`/memory` 查看，`/memory 一段话` 保存一条。
 
 ## 配置
 
-未配置服务商时，min-agent 会使用内置的 OpenRouter 模型（`openrouter/free`）。运行 `min-agent setup` 可添加或切换你自己的服务商；写在 `~/.min-agent/config.json` 里的配置优先于内置预设。
+无需配置即可使用——内置 OpenRouter 服务商（`openrouter/free`）已预设并锁定：
 
 ```bash
-min-agent setup --type ollama
-min-agent setup --type openai-compatible --url https://api.example.com/v1 --api-key "$KEY" --name groq --default-model llama-3.1-70b
-min-agent setup --switch ollama
+min-agent models    # 始终只列出: openrouter/free
 ```
 
-配置保存在 `~/.min-agent/config.json`（全局生效）。也可以在某个项目下用 `min-agent init` 初始化 `.min-agent/config.json`，仅对该项目生效（min-agent 不会自行创建它）。
+预设服务商不可修改：在其生效期间 `min-agent setup` 会拒绝添加、修改、切换或删除服务商，模型固定为 `openrouter/free`（不拉取模型列表）。设置 `MIN_AGENT_NO_BUILTIN_PROVIDER=1` 关闭预设后，才能配置自己的服务商。
+
+配置保存在 `~/.min-agent/config.json`（全局生效）。项目级配置用 `min-agent init` 创建 `.min-agent/config.json`，仅对该项目生效。
 
 ## 扩展能力
 
-- **MCP 服务**：连接外部工具与数据源，运行 `min-agent mcp -h` 了解详情
-- **技能（Skills）**：可自动加载的可复用指令集，运行 `min-agent skills -h` 了解详情
-- **项目规则**：在项目根目录添加 `AGENTS.md` 或 `RULES.md` 编写自定义指令；全局规则写入 `~/.min-agent/rules.md`
+- **MCP 服务**：连接外部工具与数据源，`min-agent mcp -h`
+- **技能（Skills）**：可自动加载的可复用指令集，`min-agent skills -h`
+- **项目规则**：在项目里添加 `AGENTS.md` 或 `RULES.md`；全局规则写入 `~/.min-agent/rules.md`
 
 ## API 接入
 
@@ -263,4 +215,4 @@ min-agent setup --switch ollama
 
 ## License
 
-MIT
+MIT