min-agent 0.5.1 → 0.6.1

package/docs/API.md

@@ -1,6 +1,6 @@
 # min-agent HTTP API
 
-`min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。
+`min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。未配置服务商时使用内置 OpenRouter 模型，不必先运行 `min-agent setup`。
 
 ## 启动
 
@@ -21,6 +21,8 @@ min-agent serve --host 0.0.0.0 --port 3000
 > CORS 未设置 token 时仅允许 localhost Origin（无 Origin 头的请求不受限）；非 localhost Origin 返回 `403 origin_not_allowed`。设置 `MIN_AGENT_SERVE_TOKEN` 后不受 Origin 限制。
 >
 > 会话 ID 仅接受 `[A-Za-z0-9_-]+`，非法 ID 一律返回 404/400，防止路径穿越。
+>
+> 项目级写入：`scope: "project"` 的写接口（`/v1/permission`、`/v1/thinking`、`/v1/sandbox`、`/v1/budget`、`/v1/memory`、`/v1/mcp`、`/v1/skills/:name/enable|disable` 等）只有当前目录已存在 `.min-agent/`（由 `min-agent init` 创建）时才会落盘；目录不存在时写操作被跳过（响应仍返回成功，stderr 会打印跳过警告）。
 
 ---
 
@@ -91,7 +93,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`
@@ -226,7 +228,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 | 致命错误 |
 
 ---
@@ -338,10 +340,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`
 
@@ -415,7 +417,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.1",
+  "version": "0.6.1",
   "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

@@ -19,9 +19,9 @@ This skill is already loaded. Follow it whenever the user asks to change min-age
 | Global | `~/.min-agent/` (`MIN_AGENT_CONFIG_DIR` replaces this) | All projects; API keys live only here |
 | Project | `<cwd>/.min-agent/` | This repo only |
 
-If the user does not say which scope: use **project** when `.min-agent/` exists, otherwise **global**. Never put `apiKey`, `token`, `serperApiKey`, or other secrets in project files.
+Never create `.min-agent/` yourself. It exists only after the user ran `min-agent init` (or created the folder on their own). Project scope is available only when `.min-agent/` already exists — otherwise use **global**. If the user wants project config in a directory without it, tell them to run `min-agent init` first. Never put `apiKey`, `token`, `serperApiKey`, or other secrets in project files.
 
-Config files are **strict JSON** (no comments). Read the file before editing. Prefer the `edit` tool for existing files; `write` only when creating a new file. Keep unrelated keys. Create parent directories when needed.
+Config files are **strict JSON** (no comments). Read the file before editing. Prefer the `edit` tool for existing files; `write` only when creating a new file. Keep unrelated keys. Create parent directories when needed — except `.min-agent/` itself.
 
 ## What goes where
 
@@ -80,13 +80,15 @@ 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.
+- 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.
 

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": {
@@ -71,6 +71,8 @@ Read this when you need exact keys. Files are strict JSON.
 - 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`
 
@@ -141,6 +143,7 @@ Array of `{ "content": string, "tags": string[], "created": string }`. Prefer me
 | `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` |