min-agent 0.2.1 → 0.3.0

package/docs/API.md

@@ -16,6 +16,12 @@ min-agent serve --host 0.0.0.0 --port 3000
 | `MIN_AGENT_SERVE_TOKEN` | Bearer token 鉴权 |
 | `MIN_AGENT_SERVE_CORS` | 设为 `1` 启用 CORS |
 
+> 安全：当监听地址不是 loopback（`127.0.0.1`/`::1`/`localhost`）时，必须设置 `MIN_AGENT_SERVE_TOKEN`，否则服务拒绝启动。`/v1/chat`、`/v1/code` 与 `/v1/paste` 最多支持 8 个并发请求，超出返回 `429`。
+>
+> CORS 未设置 token 时仅允许 localhost Origin（无 Origin 头的请求不受限）；非 localhost Origin 返回 `403 origin_not_allowed`。设置 `MIN_AGENT_SERVE_TOKEN` 后不受 Origin 限制。
+>
+> 会话 ID 仅接受 `[A-Za-z0-9_-]+`，非法 ID 一律返回 404/400，防止路径穿越。
+
 ---
 
 ## 端点一览
@@ -41,8 +47,18 @@ min-agent serve --host 0.0.0.0 --port 3000
 | GET | `/v1/mcp` | MCP 状态 |
 | POST | `/v1/mcp` | 添加 MCP 服务器 |
 | DELETE | `/v1/mcp/:name` | 删除 MCP 服务器 |
-| GET | `/v1/skills` | 技能列表 |
+| GET | `/v1/skills` | 技能列表（含启用状态） |
+| GET | `/v1/skills/:name` | 技能详情（含正文） |
+| POST | `/v1/skills/reload` | 重新扫描技能目录 |
 | GET | `/v1/rules` | 已加载规则 |
+| GET | `/v1/sessions/:id` | 会话详情 |
+| POST | `/v1/sessions/:id/rename` | 重命名会话 |
+| POST | `/v1/chat/undo` | 撤销最后一轮 |
+| POST | `/v1/skills/:name/enable` | 启用技能 |
+| POST | `/v1/skills/:name/disable` | 禁用技能 |
+| POST | `/v1/mcp/:name/enable` | 启用 MCP 服务器 |
+| POST | `/v1/mcp/:name/disable` | 禁用 MCP 服务器 |
+| GET | `/v1/cost` | 模型价格与成本估算 |
 
 ---
 
@@ -97,9 +113,13 @@ min-agent serve --host 0.0.0.0 --port 3000
 | `message` | string | 用户消息（与 `messages` 二选一） |
 | `messages` | array | 完整 ModelMessage[] |
 | `model` | string | 覆盖模型 |
+| `provider` | string | 指定 provider（默认 activeProvider） |
 | `stream` | boolean | SSE 流式 |
 | `session_id` | string | 恢复会话 |
 | `images` | string[] | 本地图片路径 |
+| `temperature` | number | 采样温度（透传模型 API） |
+| `maxTokens` | number | 最大输出 token 数 |
+| `topP` | number | 核采样参数 |
 
 ### 非流式响应
 
@@ -127,7 +147,7 @@ min-agent serve --host 0.0.0.0 --port 3000
 | `tool_result` | name, output | 工具返回 |
 | `compaction` | line | 压缩进度 |
 | `error` | message | 错误 |
-| `done` | step_count, usage, messages, session_id | 结束 |
+| `done` | step_count, usage, has_error, aborted, max_steps_reached, budget_exceeded, messages, session_id | 结束 |
 | `fatal` | message | 致命错误 |
 
 ---
@@ -153,8 +173,19 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 | `mime_type` | string | MIME 类型（默认 `image/png`） |
 | `message` | string | 文本 prompt |
 | `model` | string | 覆盖模型 |
+| `provider` | string | 指定 provider（默认 activeProvider） |
 | `session_id` | string | 追加到会话 |
 | `stream` | boolean | SSE 流式 |
+| `code` | boolean | 使用 code 模式（项目感知） |
+| `temperature` | number | 采样温度 |
+| `maxTokens` | number | 最大输出 token 数 |
+| `topP` | number | 核采样参数 |
+
+`stream: true` 时 SSE 事件与 `/v1/chat` 一致（含 `X-Accel-Buffering: no` 响应头、`done` 事件的 usage/has_error/aborted/max_steps_reached/messages 字段）；非流式响应与 `/v1/chat` 非流式响应结构一致。
+
+`session_id` 不存在时返回 `404 session_not_found`（与 `/v1/chat` 一致）。
+
+`code: true` 时非流式响应额外包含 `mode: "code"` 与 `project` 字段。
 
 ---
 
@@ -167,6 +198,111 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 { "ok": true, "compacted": true, "message_count": 5 }
 ```
 
+## `GET /v1/sessions/:id`
+
+```json
+{ "session": { "meta": { "id": "abc", "title": "...", ... }, "messages": [...] } }
+```
+
+## `POST /v1/sessions/:id/rename`
+
+```json
+// 请求
+{ "title": "new title" }
+// 响应
+{ "ok": true, "session_id": "abc", "title": "new title" }
+```
+
+## `POST /v1/chat/undo`
+
+```json
+// 请求
+{ "session_id": "abc123" }
+// 响应
+{ "ok": true, "message_count": 3, "messages": [...] }
+```
+
+截断到最后一条 user 消息（保留该消息，删除其后的 assistant/tool 消息）。
+
+## `GET /v1/skills`
+
+```json
+{
+  "count": 2,
+  "enabled_count": 1,
+  "stale_disabled": ["removed-skill"],
+  "skills": [
+    {
+      "name": "my-skill",
+      "description": "What it does",
+      "location": "/path/.min-agent/skills/my-skill/SKILL.md",
+      "enabled": true,
+      "version": "1.0.0",
+      "allowed_tools": ["read"],
+      "requires_bins": ["some-cli"]
+    }
+  ]
+}
+```
+
+禁用项额外带 `disabled_scope`（`global` 或 `project`）。
+`stale_disabled` 列出两个范围的 `disabledSkills` 中没有对应技能的名字（拼写错误或技能已删除）。
+
+## `GET /v1/skills/:name`
+
+返回单个技能，附带 `content`（SKILL.md 正文）。技能不存在返回 404 `{ "error": "skill_not_found", "available": [...] }`。
+
+## `POST /v1/skills/reload`
+
+重新扫描技能目录（新增/修改 SKILL.md 后无需重启服务）。
+
+```json
+{ "ok": true, "count": 2, "enabled_count": 1, "stale_disabled": [], "skills": [...] }
+```
+
+## `POST /v1/skills/:name/enable` / `/disable`
+
+请求体可选：
+
+```json
+{ "scope": "project" }
+```
+
+`scope` 为 `global`（默认，写 `~/.min-agent/config.json`）或 `project`（写 `.min-agent/config.json`）。项目范围优先于全局，因此全局禁用的技能可以在单个项目里用 `{"scope":"project"}` 的 enable 重新启用。
+
+```json
+{ "ok": true, "name": "my-skill", "enabled": false, "scope": "project" }
+```
+
+若改动被另一范围覆盖，响应带 `blocked_by`（`global` 或 `project`），`enabled` 反映实际生效状态。
+技能不存在返回 404 `{ "error": "skill_not_found", "available": [...] }`；`scope` 非法返回 400 `{ "error": "invalid_scope" }`。
+
+## `POST /v1/mcp/:name/enable` / `/disable`
+
+请求体可选：
+
+```json
+{ "scope": "project" }
+```
+
+`scope` 为 `global`（默认，写 `~/.min-agent/mcp.json`）或 `project`（写 `.min-agent/mcp.json`）。服务器在另一范围时返回 404 并带 `hint`。
+
+```json
+{ "ok": true, "name": "fs", "enabled": true, "scope": "global", "connected": true }
+```
+
+## `GET /v1/cost`
+
+| 参数 | 说明 |
+|------|------|
+| `model` | 模型 ID（默认配置默认模型） |
+| `input` | 输入 token 数 |
+| `output` | 输出 token 数 |
+
+```json
+{ "model": "gpt-4o", "price": { "inputPerMillion": 2.5, "outputPerMillion": 10 }, "cost_usd": 7.5 }
+```
+
 ## `POST /v1/chat/reload-instructions`
 
 ```json
@@ -221,36 +357,45 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 ## `GET /v1/mcp`
 
 ```json
-{ "servers": { "filesystem": { "connected": true, "tools": ["read_file", "write_file"] } } }
+{
+  "servers": {
+    "filesystem": { "connected": true, "enabled": true, "tools": ["read_file", "write_file"] },
+    "broken": { "connected": false, "enabled": true, "tools": [], "error": "connection timed out after 30000ms" }
+  }
+}
 ```
 
 ## `POST /v1/mcp`
 
+添加或覆盖一个 MCP 服务器。保存后立即重连（`sync`），响应带实时状态。
+
 ```json
 // 本地 stdio
 { "name": "fs", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+// 本地 stdio（字符串 + args）
+{ "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
 // 远程
-{ "name": "remote", "url": "https://mcp.example.com", "token": "xxx" }
+{ "name": "remote", "url": "https://mcp.example.com", "token": "xxx", "remoteTransport": "sse" }
+// 项目范围（写 .min-agent/mcp.json）
+{ "name": "fs", "command": ["..."], "project": true }
 ```
 
+支持的字段：`name`（必填）、`command`（数组或字符串）、`args`、`url`、`token`、`headers`、`environment`、`remoteTransport`（`streamable-http`/`sse`/`auto`，非法值返回 400）、`timeout`、`connectTimeout`、`callTimeout`、`enabled`、`project`。
+
 ```json
-{ "ok": true, "name": "fs" }
+{ "ok": true, "name": "fs", "scope": "global", "connected": true, "tools": ["read_file"] }
 ```
 
 ## `DELETE /v1/mcp/:name`
 
+`?project=1` 删除项目范围（`.min-agent/mcp.json`）的条目；默认全局。服务器在另一范围时返回 404 并带 `hint`。
+
 ```json
-{ "ok": true, "deleted": "fs" }
+{ "ok": true, "deleted": "fs", "scope": "global" }
 ```
 
 ---
 
-## `GET /v1/skills`
-
-```json
-{ "skills": [{ "name": "git-workflow", "description": "...", "location": "..." }] }
-```
-
 ## `GET /v1/rules`
 
 ```json
@@ -263,10 +408,11 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 
 | 状态 | 说明 |
 |------|------|
-| 400 | 请求参数错误 |
+| 400 | 请求参数错误 / JSON 解析失败（`invalid_json`） |
 | 401 | 未授权 |
 | 404 | 资源不存在 |
-| 413 | 请求体过大（>2MB） |
+| 408 | 请求体读取超时（`payload_timeout`，30s） |
+| 413 | 请求体过大（>2MB，`payload_too_large`） |
 | 415 | Content-Type 不是 JSON |
 | 500 | 内部错误 |