min-agent 0.5.0 → 0.6.0

package/docs/API.md

@@ -1,6 +1,6 @@
 # min-agent HTTP API
 
-`min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。
+`min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。未配置服务商时使用内置 OpenRouter 模型，不必先运行 `min-agent setup`。
 
 ## 启动
 
@@ -33,6 +33,7 @@ min-agent serve --host 0.0.0.0 --port 3000
 | GET | `/v1/update` | 检查 npm 是否有新版本（不执行安装） |
 | GET | `/v1/models` | 模型列表 |
 | GET | `/v1/context` | 上下文窗口信息 |
+| POST | `/v1/context` | 设置本地模型上下文档位 |
 | GET | `/v1/project` | 项目扫描 |
 | POST | `/v1/chat` | 对话（项目感知） |
 | POST | `/v1/code` | 与 `/v1/chat` 相同（兼容路径） |
@@ -90,7 +91,7 @@ min-agent serve --host 0.0.0.0 --port 3000
 ## `GET /v1/meta`
 
 ```json
-{ "version": "0.1.0", "cwd": "/path/to/project", "instructions_chars": 1234, "sandbox": { "mode": "off", "network": "allow", "extraWriteRoots": [], "extraReadRoots": [], "source": null, "label": "未隔离，允许联网" }, "permission": { "permission": "ask", "source": null, "label": "询问确认" }, "thinking": { "thinking": "medium", "source": null, "label": "medium" }, "memory": { "memory": "off", "source": null, "label": "off" } }
+{ "version": "0.1.0", "cwd": "/path/to/project", "instructions_chars": 1234, "sandbox": { "mode": "off", "network": "allow", "extraWriteRoots": [], "extraReadRoots": [], "source": null, "label": "未隔离，允许联网" }, "permission": { "permission": "accept-edits", "source": null, "label": "accept edits" }, "thinking": { "thinking": "medium", "source": null, "label": "medium" }, "memory": { "memory": "off", "source": null, "label": "off" } }
 ```
 
 ## `GET /v1/update`
@@ -118,10 +119,26 @@ CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
 ## `GET /v1/context`
 
 ```json
-{ "context_window": 1000000, "source": "config", "model": "gpt-4o" }
+{ "context_window": 1000000, "source": "config", "model": "gpt-4o", "configurable": false, "level": null }
 ```
 
-`source` 为 `config`（配置中的 `contextWindow`）、`detected`（从接口读到）或 `fallback`（未读到，按 512k 处理）。
+`source` 为 `config`（配置中的 `contextWindow`）、`detected`（从接口读到）或 `fallback`（未读到：Ollama 按 2048，其余按 512k）。Ollama 的 detected 值是运行时窗口（优先 Modelfile `num_ctx`，否则不超过 32768），不是架构标称上限。对话请求走原生 `/api/chat` 并带上该窗口；只改 OpenAI 兼容接口的 `num_ctx` 不会生效。
+
+当前为 Ollama 时额外返回 `configurable: true` 与 `level`（`2k`…`256k` 或 `auto`）。其它 provider 为 `configurable: false`、`level: null`。
+
+## `POST /v1/context`
+
+仅 Ollama provider。将当前 provider 的 `contextWindow` 写成对应档位；`auto` 删除覆盖，回到探测值。
+
+```json
+{ "level": "8k" }
+```
+
+```json
+{ "ok": true, "context_window": 8192, "source": "config", "model": "qwen3:4b", "configurable": true, "level": "8k" }
+```
+
+非法档位返回 `400 invalid_context_level`。当前不是 Ollama 时返回 `400 ctx_not_supported`。
 
 ## `GET /v1/project`
 
@@ -209,7 +226,7 @@ CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
 | `error` | message | 错误 |
 | `done` | step_count, usage, context_tokens, has_error, aborted, max_steps_reached, incomplete, budget_exceeded, continues, stopped, empty_response, empty_attempts, messages, session_id, task_state, project | 结束 |
 | `confirm` | id, message | 等待确认（仅 `auto_approve: false`） |
-| `question` | id, prompt, options | 等待回答（仅 `auto_approve: false`）。`options` 为字符串数组；对象选项（如 `{label, description}`）会先被规范成字符串再下发 |
+| `question` | id, prompt, options, multiple | 等待回答（仅 `auto_approve: false`）。`options` 为字符串数组；对象选项（如 `{label, description}`）会先被规范成字符串再下发。有选项时末尾会补上「其他」以便自定义输入。`multiple: true` 表示可多选 |
 | `fatal` | message | 致命错误 |
 
 ---
@@ -321,10 +338,10 @@ CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
 ## `GET /v1/permission`
 
 ```json
-{ "permission": "ask", "source": null, "label": "询问确认" }
+{ "permission": "accept-edits", "source": null, "label": "accept edits" }
 ```
 
-`permission` 为 `ask` / `accept-edits` / `allow-all`。`source` 为 `cli`、`project`、`global` 或 `null`（使用默认：询问确认）。
+`permission` 为 `ask` / `accept-edits` / `allow-all`。`source` 为 `cli`、`project`、`global` 或 `null`（使用默认：`accept-edits`，自动允许文件修改）。
 
 ## `POST /v1/permission`
 
@@ -398,7 +415,7 @@ CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
 
 ## `POST /v1/answers`
 
-配合 SSE `question` 事件。`answer` 为 `null` 表示跳过。
+配合 SSE `question` 事件。`answer` 为 `null` 表示跳过。单选传选项原文或自定义文字；多选可传 JSON 字符串数组（如 `["A","自定义"]`），或单个字符串。
 
 ```json
 // 请求

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "min-agent",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",
   "bin": {
-    "min-agent": "./bin/min-agent.js"
+    "min-agent": "bin/min-agent.js"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -13,7 +13,7 @@
   "files": [
     "bin",
     "dist",
-    "docs",
+    "docs/API.md",
     "skills",
     "README.md",
     "LICENSE"
@@ -31,11 +31,11 @@
   "homepage": "https://gitee.com/lemon8510/min-agent",
   "scripts": {
     "dev": "bun run src/cli.ts",
-    "build": "tsc",
+    "build": "bun run scripts/bundle.ts",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "lint": "biome check src tests",
-    "format": "biome format --write src tests",
+    "lint": "biome check src tests scripts",
+    "format": "biome format --write src tests scripts",
     "prepack": "npm run typecheck && npm run build"
   },
   "keywords": [

package/skills/self-config/SKILL.md

@@ -80,12 +80,16 @@ Instructions...
 
 - Rules: edit the files in the table above. `/reload` reloads rules only, not MCP.
 - Memory: **off** by default. Config `memory` is `on` | `off` (`true`/`enable` → on, `false`/`disable` → off). Project overlays global; writing `memory` globally also removes a project `memory` overlay. When off, memories are not injected and `memory_save` / `memory_search` / `memory_delete` are not registered (takes effect next turn after you change the file). CLI `min-agent memory on|off` / `--memory` follow the same write-vs-this-run rule as permission. `/memory on|off` writes **global** by default (and clears a project overlay); `/memory --project` writes only the project file. `/memory` lists the switch plus stored entries; `/memory <text>` still writes `memory.json` even when off. Default save scope is project when `.min-agent/` exists. Shape: `{ "content": string, "tags": string[], "created": ISO string }` array. When on, memories are injected each turn as background reference, not as work to resume. Do not store secrets or API keys. HTTP: `GET/POST /v1/memory/mode`, chat body `memory`, and `GET /v1/memory` include `memory` / `source` / `label`.
-- Permission: `ask` (default) | `accept-edits` | `allow-all` in config `permission`. CLI `min-agent permission …` / `--permission` without a message writes config and exits; with a message it is this session only. `--yes` is this session only and does not write config.
-- Thinking intensity: `off` | `low` | `medium` | `high` | `max` in config `thinking`. Omit the field to use **medium**, then clamp to levels the current model actually exposes (from the model catalog). `/think` opens an interactive picker of those English levels and writes **global** config; that also clears a project `thinking` overlay so a leftover project `off` cannot hide the new value after restart. `/think --project` writes only the project file. Typed `/think off|low|medium|high|max` still works when the model supports that value. `min-agent think …` / `--think` follow the same write-vs-this-run rule as permission. `xhigh` / `extra-high` / `none` are accepted as aliases (`xhigh` → `max`, `none` → `off`). Each request maps that intensity onto the current model and gateway (MiniMax uses `adaptive`/`disabled`; official OpenAI omits `thinking` and maps `max` to `xhigh`). Learned mappings are cached in `~/.min-agent/thinking-wire-cache.json` for 7 days. Per-model context window and supported effort values are loaded from the model catalog (`https://models.lonae.com`, override with `MIN_AGENT_MODELS_API_URL`) and cached in `~/.min-agent/model-catalog-cache.json` for 7 days after a successful lookup. When the provider host is unknown, effort levels are the majority across offerings that actually list efforts (toggle-only rows do not vote), so a single gateway cannot invent `medium`.
+- Permission: `accept-edits` (default) | `ask` | `allow-all` in config `permission`. CLI `min-agent permission …` / `--permission` without a message writes config and exits; with a message it is this session only. `--yes` is this session only and does not write config.
+- Thinking intensity: `off` | `low` | `medium` | `high` | `max` in config `thinking`. Omit the field to use **medium**, then clamp to levels the current model actually exposes (from the model catalog). `/think` opens an interactive picker of those English levels and writes **global** config; that also clears a project `thinking` overlay so a leftover project `off` cannot hide the new value after restart. `/think --project` writes only the project file. Typed `/think off|low|medium|high|max` still works when the model supports that value. `min-agent think …` / `--think` follow the same write-vs-this-run rule as permission. `xhigh` / `extra-high` / `none` are accepted as aliases (`xhigh` → `max`, `none` → `off`). Each request maps that intensity onto the current model and gateway (MiniMax uses `adaptive`/`disabled`; official OpenAI omits `thinking` and maps `max` to `xhigh`; an `ollama` provider uses native chat with `think` plus the configured window). Learned mappings are cached in `~/.min-agent/thinking-wire-cache.json` for 7 days. Per-model context window and supported effort values are loaded from the model catalog (`https://models.lonae.com`, override with `MIN_AGENT_MODELS_API_URL`) and cached in `~/.min-agent/model-catalog-cache.json` for 7 days after a successful lookup. When the provider host is unknown, effort levels are the majority across offerings that actually list efforts (toggle-only rows do not vote), so a single gateway cannot invent `medium`. An `ollama` provider skips that catalog and uses native `POST /api/show` instead (whether the model advertises thinking, plus the loaded window: Modelfile `num_ctx` if set, otherwise the architecture length capped at 32768). Chat completions are sent to native `POST /api/chat` so `options.num_ctx` and `think` actually apply — the OpenAI-compatible `/v1` endpoint ignores both. `/ctx` opens a picker of `2k` / `4k` / `8k` / `12k` / `16k` / `32k` / `64k` / `128k` / `256k` / `auto` and writes the active provider's `contextWindow` (global only; providers are not in project config). Typed `/ctx 8k` and CLI `min-agent ctx 8k` do the same; `auto` clears the override. The menu item is hidden unless the active provider is ollama. Results are cached in `~/.min-agent/ollama-model-cache.json` for 7 days.
 - Sandbox default is **off**. `mode`: `off` | `workspace` | `strict`. Optional `network`, `extraWriteRoots`, `extraReadRoots`. Isolation is independent of permission. `--sandbox` / `--network` without a message write config and exit.
 
 ## Providers
 
-Only in global `config.json`: `providers[]` with `name`, `type` (`openai-compatible` | `openai` | `ollama`), `baseURL`, `apiKey`, optional `defaultModel`, `contextWindow`. `activeProvider` selects one. Project config may set `activeProvider` and `defaultModel` (no keys).
+Only in global `config.json`: `providers[]` with `name`, `type` (`openai-compatible` | `openai` | `ollama`), `baseURL`, `apiKey`, optional `defaultModel`, `contextWindow`. `activeProvider` selects one. Project config may set `activeProvider` and `defaultModel` (no keys). If `providers` is missing or empty, a built-in OpenRouter provider (`openrouter`, model `openrouter/free`) is used at runtime and is not written to disk. User-configured providers always win. `MIN_AGENT_NO_BUILTIN_PROVIDER=1` disables the fallback.
+
+`/provider` opens an interactive picker and writes **global** `activeProvider`; that also clears a project `activeProvider` overlay so the choice is what later turns use. Typed `/provider <name>` still works. Adding, editing, or removing providers is `min-agent setup` (not the TUI picker).
+
+CLI: `min-agent setup` (interactive wizard or flags). Flags: `--type openai-compatible|openai|ollama`, `--url`, `--api-key`, `--name`, `--default-model`, `--switch <name>`, `--remove <name>`. `--yes` skips overwrite/delete confirmation during setup; it does not change permission. Keys only in the global file.
 
 After changing keys or MCP connections, tell the user if a restart is required. Do not print full secrets back in chat.

package/skills/self-config/reference.md

@@ -23,7 +23,7 @@ Read this when you need exact keys. Files are strict JSON.
   "webFetchURL": "https://firecrawl.example.com",
   "instructions": ["./docs/rules.md"],
   "disabledSkills": [],
-  "permission": "ask",
+  "permission": "accept-edits",
   "thinking": "max",
   "memory": "on",
   "sandbox": {
@@ -58,7 +58,7 @@ Read this when you need exact keys. Files are strict JSON.
 
 - `thinking`: `off` | `low` | `medium` | `high` | `max`; omit to use medium. A project `thinking` value overlays global; writing thinking globally removes the project overlay so the chosen level is what later sessions use. `/think --project` writes only the project file.
 - `memory`: `on` | `off`; omit to keep **off**. When off, stored `memory.json` entries are not injected and memory tools are unavailable. A project `memory` value overlays global; writing memory globally removes the project overlay. `/memory --project` writes only the project file.
-- `contextWindow`: tokens; omit to query the API, then 512k fallback.
+- `contextWindow`: tokens; omit to query the API. An `ollama` provider uses `POST /api/show`: Modelfile `num_ctx` if set, otherwise min(architecture context_length, 32768), else 2048. Chat goes to native `POST /api/chat` with that value as `options.num_ctx` (OpenAI-compatible `/v1` ignores it). Interactive `/ctx` (and `min-agent ctx`) sets this field on the active ollama provider to a fixed level (`2k` / `4k` / `8k` / `12k` / `16k` / `32k` / `64k` / `128k` / `256k`) or `auto` to clear it. Other providers then 512k fallback.
 - `agent.autoContinue` omitted → uses `compaction.autoContinue` (default true).
 - `agent.maxSteps` omitted → no tool-step ceiling.
 - `agent.maxEmptyAttempts` / `agent.emptyRetryDelayMs`: retries when the provider returns an empty stream (HTTP 200, no content). First retry is immediate, later ones back off exponentially, capped at 8s.
@@ -70,6 +70,9 @@ Read this when you need exact keys. Files are strict JSON.
 - `MIN_AGENT_TRACE=1` logs a request/response summary for every model call (model, message and tool counts, status, time to first byte).
 - Web search/fetch that has not yet produced the requested output still continues even when `autoContinue` is false; further search/fetch calls return a stop-and-write notice instead of new results.
 - Old single-provider configs migrate on first run; write the `providers` array for new files.
+- Interactive and non-interactive provider setup both go through `min-agent setup`. API keys are written only to the global config.
+- Interactive `/provider` (and typed `/provider <name>`) writes global `activeProvider` and clears a project `activeProvider` overlay. It does not add, edit, or remove providers.
+- If `providers` is missing or empty, runtime uses a built-in OpenRouter provider (`name`: `openrouter`, `defaultModel`: `openrouter/free`) without writing it to disk. User entries always win. `MIN_AGENT_NO_BUILTIN_PROVIDER=1` disables that fallback.
 
 ## Project `.min-agent/config.json`
 
@@ -137,9 +140,10 @@ Array of `{ "content": string, "tags": string[], "created": string }`. Prefer me
 
 | Variable | Role |
 |----------|------|
-| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` (includes `model-catalog-cache.json`, `thinking-wire-cache.json`) |
+| `MIN_AGENT_CONFIG_DIR` | Replaces `~/.min-agent` (includes `model-catalog-cache.json`, `thinking-wire-cache.json`, `ollama-model-cache.json`) |
 | `MIN_AGENT_SKILLS_DIRS` | Replaces user skill roots (path-delimiter separated) |
 | `MIN_AGENT_NO_BUILTIN_SKILLS` | `1` / `true` skips packaged skills |
+| `MIN_AGENT_NO_BUILTIN_PROVIDER` | `1` / `true` skips the built-in OpenRouter fallback |
 | `MIN_AGENT_SANDBOX` / `MIN_AGENT_SANDBOX_NETWORK` | Isolation |
 | `MIN_AGENT_MODELS_API_URL` | Model catalog base (default `https://models.lonae.com`) |
 | `MIN_AGENT_SERPER_API_KEY` | Overrides `serperApiKey` |
@@ -151,4 +155,4 @@ Array of `{ "content": string, "tags": string[], "created": string }`. Prefer me
 
 ## HTTP (only if the user is running `min-agent serve`)
 
-Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Thinking: `GET/POST /v1/thinking`. Memory switch: `GET/POST /v1/memory/mode`. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.
+Skills: `GET /v1/skills`, `GET /v1/skills/:name`, `POST /v1/skills/reload`, `POST /v1/skills/:name/enable|disable` with `{ "scope": "project"|"global" }`. MCP enable/disable similarly. Thinking: `GET/POST /v1/thinking`. Memory switch: `GET/POST /v1/memory/mode`. Ollama context level: `GET/POST /v1/context` with `{ "level": "8k" }` or `"auto"`. Full list is `docs/API.md` in the min-agent package; do not treat that file as this skill's replacement.