min-agent 0.6.7 → 0.6.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/dist/cli.js +264 -262
  2. package/package.json +1 -2
  3. package/docs/API.md +0 -757
package/docs/API.md DELETED
@@ -1,757 +0,0 @@
1
- # min-agent HTTP API
2
-
3
- `min-agent serve` 启动本地 HTTP 服务，以编程方式调用代理能力。未配置服务商时使用内置 OpenRouter 模型（`openrouter/free`，预设锁定、不可修改），不必先运行 `min-agent setup`。
4
-
5
- ## 启动
6
-
7
- ```bash
8
- min-agent serve
9
- min-agent serve --host 0.0.0.0 --port 3000
10
- ```
11
-
12
- | 环境变量 | 说明 |
13
- |----------|------|
14
- | `MIN_AGENT_SERVE_HOST` | 监听地址（默认 `127.0.0.1`） |
15
- | `MIN_AGENT_SERVE_PORT` | 端口（默认 `8787`） |
16
- | `MIN_AGENT_SERVE_TOKEN` | Bearer token 鉴权 |
17
- | `MIN_AGENT_SERVE_CORS` | 设为 `1` 启用 CORS |
18
-
19
- > 安全：当监听地址不是 loopback（`127.0.0.1`/`::1`/`localhost`）时，必须设置 `MIN_AGENT_SERVE_TOKEN`，否则服务拒绝启动。`/v1/chat`、`/v1/code` 与 `/v1/paste` 最多支持 8 个并发请求，超出返回 `429`。
20
- >
21
- > CORS 未设置 token 时仅允许 localhost Origin（无 Origin 头的请求不受限）；非 localhost Origin 返回 `403 origin_not_allowed`。设置 `MIN_AGENT_SERVE_TOKEN` 后不受 Origin 限制。
22
- >
23
- > 会话 ID 仅接受 `[A-Za-z0-9_-]+`，非法 ID 一律返回 404/400，防止路径穿越。
24
- >
25
- > 项目级写入：`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 会打印跳过警告）。
26
-
27
- ---
28
-
29
- ## 端点一览
30
-
31
- | 方法 | 路径 | 说明 |
32
- |------|------|------|
33
- | GET | `/health` | 存活检查 |
34
- | GET | `/v1/meta` | 运行环境 |
35
- | GET | `/v1/update` | 检查 npm 是否有新版本（不执行安装） |
36
- | GET | `/v1/models` | 模型列表 |
37
- | GET | `/v1/context` | 上下文窗口信息 |
38
- | POST | `/v1/context` | 设置本地模型上下文档位 |
39
- | GET | `/v1/project` | 项目扫描 |
40
- | POST | `/v1/chat` | 对话（项目感知） |
41
- | POST | `/v1/code` | 与 `/v1/chat` 相同（兼容路径） |
42
- | POST | `/v1/paste` | 图片+文本对话 |
43
- | POST | `/v1/chat/compact` | 手动压缩会话 |
44
- | POST | `/v1/chat/reload-instructions` | 重载规则 |
45
- | POST | `/v1/chat/redo` | 重发会话最后一条用户消息 |
46
- | GET | `/v1/sessions` | 列出会话 |
47
- | DELETE | `/v1/sessions/:id` | 删除会话 |
48
- | GET | `/v1/memory` | 列出记忆（含开关状态与 `project_memories`） |
49
- | POST | `/v1/memory` | 添加记忆 |
50
- | GET | `/v1/memory/search?q=xxx` | 搜索记忆 |
51
- | DELETE | `/v1/memory/:index` | 删除记忆 |
52
- | GET | `/v1/memory/mode` | 当前记忆开关 |
53
- | POST | `/v1/memory/mode` | 设置记忆开关 |
54
- | GET | `/v1/budget` | 当前预算上限 |
55
- | POST | `/v1/budget` | 设置预算上限 |
56
- | GET | `/v1/permission` | 当前确认模式 |
57
- | POST | `/v1/permission` | 设置确认模式 |
58
- | GET | `/v1/thinking` | 当前思考强度 |
59
- | POST | `/v1/thinking` | 设置思考强度 |
60
- | GET | `/v1/sandbox` | 当前隔离策略 |
61
- | POST | `/v1/sandbox` | 设置隔离策略 |
62
- | GET | `/v1/diff` | 工作区未提交变更 |
63
- | POST | `/v1/approvals` | 回答危险操作确认 |
64
- | POST | `/v1/answers` | 回答代理提问 |
65
- | GET | `/v1/mcp` | MCP 状态 |
66
- | GET | `/v1/mcp/:name/resources` | 列出资源与 URI 模板 |
67
- | GET | `/v1/mcp/:name/prompts` | 列出 prompt 模板 |
68
- | POST | `/v1/mcp/:name/resources/read` | 读取一条资源 |
69
- | POST | `/v1/mcp/:name/prompts/get` | 填充一条 prompt |
70
- | POST | `/v1/mcp` | 添加 MCP 服务器 |
71
- | DELETE | `/v1/mcp/:name` | 删除 MCP 服务器 |
72
- | GET | `/v1/skills` | 技能列表（含启用状态） |
73
- | GET | `/v1/skills/:name` | 技能详情（含正文） |
74
- | POST | `/v1/skills/reload` | 重新扫描技能目录 |
75
- | GET | `/v1/rules` | 已加载规则 |
76
- | GET | `/v1/sessions/:id` | 会话详情 |
77
- | POST | `/v1/sessions/:id/rename` | 重命名会话 |
78
- | POST | `/v1/chat/undo` | 撤销最后一轮 |
79
- | POST | `/v1/skills/:name/enable` | 启用技能 |
80
- | POST | `/v1/skills/:name/disable` | 禁用技能 |
81
- | POST | `/v1/mcp/:name/enable` | 启用 MCP 服务器 |
82
- | POST | `/v1/mcp/:name/disable` | 禁用 MCP 服务器 |
83
- | GET | `/v1/cost` | 模型价格与成本估算 |
84
-
85
- ---
86
-
87
- ## `GET /health`
88
-
89
- ```json
90
- { "ok": true, "service": "min-agent", "version": "0.1.0" }
91
- ```
92
-
93
- ## `GET /v1/meta`
94
-
95
- ```json
96
- { "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" } }
97
- ```
98
-
99
- ## `GET /v1/update`
100
-
101
- 查询当前运行版本与 npm 上的最新版本。此接口只检查，不会执行 `npm install`。
102
-
103
- ```json
104
- { "current": "0.3.0", "latest": "0.3.1", "update_available": true }
105
- ```
106
-
107
- 无法访问 npm registry 时：
108
-
109
- ```json
110
- { "current": "0.3.0", "latest": null, "update_available": false, "error": "registry_unavailable" }
111
- ```
112
-
113
- CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
114
-
115
- ## `GET /v1/models`
116
-
117
- ```json
118
- { "default_model": "gpt-4o", "models": ["gpt-4o", "gpt-4o-mini"] }
119
- ```
120
-
121
- 当内置 OpenRouter 预设生效时，`models` 固定为 `["openrouter/free"]`（不发网络请求，也不允许其它模型）。
122
-
123
- ## `GET /v1/context`
124
-
125
- ```json
126
- { "context_window": 1000000, "source": "config", "model": "gpt-4o", "configurable": false, "level": null }
127
- ```
128
-
129
- `source` 为 `config`（配置中的 `contextWindow`）、`detected`（从接口读到）或 `fallback`（未读到：Ollama 按 2048，其余按 512k）。Ollama 的 detected 值是运行时窗口（优先 Modelfile `num_ctx`，否则不超过 32768），不是架构标称上限。对话请求走原生 `/api/chat` 并带上该窗口；只改 OpenAI 兼容接口的 `num_ctx` 不会生效。
130
-
131
- 当前为 Ollama 时额外返回 `configurable: true` 与 `level`（`2k`…`256k` 或 `auto`）。其它 provider 为 `configurable: false`、`level: null`。
132
-
133
- ## `POST /v1/context`
134
-
135
- 仅 Ollama provider。将当前 provider 的 `contextWindow` 写成对应档位；`auto` 删除覆盖，回到探测值。
136
-
137
- ```json
138
- { "level": "8k" }
139
- ```
140
-
141
- ```json
142
- { "ok": true, "context_window": 8192, "source": "config", "model": "qwen3:4b", "configurable": true, "level": "8k" }
143
- ```
144
-
145
- 非法档位返回 `400 invalid_context_level`。当前不是 Ollama 时返回 `400 ctx_not_supported`。
146
-
147
- ## `GET /v1/project`
148
-
149
- ```json
150
- {
151
- "project": {
152
- "directory": "/path",
153
- "isGitRepo": true,
154
- "branch": "main",
155
- "languages": ["TypeScript"],
156
- "framework": "Next.js",
157
- "packageManager": "bun",
158
- "entryFiles": ["src/index.ts"],
159
- "configFiles": ["package.json", "tsconfig.json"],
160
- "summary": "..."
161
- }
162
- }
163
- ```
164
-
165
- ---
166
-
167
- ## `POST /v1/chat`
168
-
169
- | 字段 | 类型 | 说明 |
170
- |------|------|------|
171
- | `message` | string | 用户消息（与 `messages` 二选一） |
172
- | `messages` | array | 完整 ModelMessage[] |
173
- | `model` | string | 覆盖模型 |
174
- | `provider` | string | 指定 provider（默认 activeProvider） |
175
- | `stream` | boolean | SSE 流式 |
176
- | `session_id` | string | 恢复会话 |
177
- | `images` | string[] | 本地图片路径 |
178
- | `temperature` | number | 采样温度（透传模型 API） |
179
- | `maxTokens` | number | 最大输出 token 数 |
180
- | `topP` | number | 核采样参数 |
181
- | `plan_mode` | boolean | 只读计划模式（去掉写入类工具） |
182
- | `auto_approve` | boolean | 默认 `true`。设为 `false` 时必须 `stream: true`，并通过 `POST /v1/approvals` / `POST /v1/answers` 回调 |
183
- | `sandbox` | string | 本轮隔离：`off` / `workspace` / `strict`。只能比服务当前策略更严，不能放宽 |
184
- | `network` | string | 本轮联网：`allow` / `deny`。`deny` 只能收紧 |
185
- | `thinking` | string | 本轮思考强度：`off` / `low` / `medium` / `high` / `max`。不传则用配置，未配置时为 `medium` |
186
- | `memory` | string | 本轮是否使用记忆：`on` / `off`。不传则用配置，未配置时为 `off` |
187
-
188
- `auto_approve: false` 且未开流式时返回 `400 auto_approve_requires_stream`。确认/提问最多等待 5 分钟，超时视为拒绝或跳过。客户端断开连接时未完成的确认视为拒绝。`auto_approve: false` 时所有需要确认的操作都会回调，包括文件写入/编辑（不再受服务端 `permission` 的 `accept-edits` 影响）；同一步的多个操作会各自发出一条 `confirm` 事件，分别用 `POST /v1/approvals` 回复。
189
-
190
- `max_steps_reached` 为 `true` 表示本轮已用尽自动续跑次数（上下文压缩/空回复等），或显式设置了 `agent.maxSteps` 且已到达该上限。默认不按固定步数切断一轮生成。`incomplete` 为 `true` 表示模型在调用工具后没有给出完整回复，或连续多次空回复。`stopped` 为 `true` 表示因同一操作反复执行而主动结束本轮。`empty_response` 为 `true` 表示 provider 连续返回空流（HTTP 200 但没有任何内容，多为上游超时/限流），`empty_attempts` 为已尝试次数；这类空回复会以原请求重发重试（首次立即，之后指数退避），可用 `agent.maxEmptyAttempts`（默认 4）与 `agent.emptyRetryDelayMs`（默认 1000）调整。发送下一条消息即可继续。`continues` 为本轮实际自动续跑次数。`task_state` 为当前任务目标与待办列表，会写入会话并在压缩后保留；纯问候不会记为任务目标。网页检索连续过久、或检索后尚未写出用户要求的结果时，代理会改为基于已有资料产出结果；本轮内再调用搜索/抓取会收到停止检索并直接产出的提示，而不是新的检索结果（即使 `autoContinue` 为 `false`）。
191
-
192
- ### 非流式响应
193
-
194
- ```json
195
- {
196
- "messages": [...],
197
- "assistant": { "role": "assistant", "content": "..." },
198
- "tool_calls": [{ "name": "bash", "input": {...} }],
199
- "tool_results": [{ "name": "bash", "output": "..." }],
200
- "session_id": "abc123",
201
- "step_count": 2,
202
- "usage": { "inputTokens": 1200, "outputTokens": 300 },
203
- "context_tokens": 1200,
204
- "has_error": false,
205
- "aborted": false,
206
- "max_steps_reached": false,
207
- "incomplete": false,
208
- "budget_exceeded": false,
209
- "continues": 0,
210
- "stopped": false,
211
- "empty_response": false,
212
- "empty_attempts": 0,
213
- "task_state": { "goal": "...", "todos": [], "nextId": 1 },
214
- "project": { "languages": [...], "directory": "...", "...": "..." }
215
- }
216
- ```
217
-
218
- `usage` 为本轮各次模型请求的 token 合计（计费口径；多步工具调用会把每次请求的 input 加总）。`context_tokens` 为最近一次请求占用的上下文大小，用来衡量窗口占用，不要把 `usage.inputTokens` 当占用百分比的分子。
219
-
220
- ### 流式 SSE 事件
221
-
222
- | type | 字段 | 说明 |
223
- |------|------|------|
224
- | `assistant` | text | 正文增量 |
225
- | `thinking` | text | 思考片段 |
226
- | `tool_call` | name, input | 工具调用 |
227
- | `tool_result` | name, output | 工具返回 |
228
- | `compaction` | line | 压缩进度 |
229
- | `notice` | kind, attempt, max_attempts, delay_ms | 提示（目前只有 `kind: "empty_response"`，表示 provider 返回空流后即将重发同一请求） |
230
- | `error` | message | 错误 |
231
- | `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 | 结束 |
232
- | `confirm` | id, message | 等待确认（仅 `auto_approve: false`） |
233
- | `question` | id, prompt, options, multiple | 等待回答（仅 `auto_approve: false`）。`options` 为字符串数组；对象选项（如 `{label, description}`）会先被规范成字符串再下发。有选项时末尾会补上「其他」以便自定义输入。`multiple: true` 表示可多选 |
234
- | `fatal` | message | 致命错误 |
235
-
236
- ---
237
-
238
- ## `POST /v1/code`
239
-
240
- 与 `/v1/chat` 相同的兼容路径。请求体与响应结构一致（含 `project`）。
241
-
242
- ---
243
-
244
- ## `POST /v1/paste`
245
-
246
- 图片 + 文本多模态对话。
247
-
248
- | 字段 | 类型 | 说明 |
249
- |------|------|------|
250
- | `image_base64` | string | **必填** Base64 图片数据 |
251
- | `mime_type` | string | MIME 类型（默认 `image/png`） |
252
- | `message` | string | 文本 prompt |
253
- | `model` | string | 覆盖模型 |
254
- | `provider` | string | 指定 provider（默认 activeProvider） |
255
- | `session_id` | string | 追加到会话 |
256
- | `stream` | boolean | SSE 流式 |
257
- | `temperature` | number | 采样温度 |
258
- | `maxTokens` | number | 最大输出 token 数 |
259
- | `topP` | number | 核采样参数 |
260
- | `plan_mode` | boolean | 只读计划模式 |
261
- | `auto_approve` | boolean | 同 `/v1/chat` |
262
-
263
- `stream: true` 时 SSE 事件与 `/v1/chat` 一致（含 `X-Accel-Buffering: no` 响应头、`done` 事件的 usage/context_tokens/has_error/aborted/max_steps_reached/incomplete/continues/stopped/empty_response/empty_attempts/task_state/messages 字段）；非流式响应与 `/v1/chat` 非流式响应结构一致。
264
-
265
- `session_id` 不存在时返回 `404 session_not_found`（与 `/v1/chat` 一致）。
266
-
267
- 非流式响应与 `/v1/chat` 相同，始终包含 `project`。请求里多传 `code` 会被忽略。
268
-
269
- ---
270
-
271
- ## `POST /v1/chat/compact`
272
-
273
- ```json
274
- // 请求
275
- { "session_id": "abc123" }
276
- // 响应
277
- { "ok": true, "compacted": true, "message_count": 5 }
278
- ```
279
-
280
- ## `GET /v1/sessions/:id`
281
-
282
- ```json
283
- {
284
- "session": {
285
- "meta": { "id": "abc", "title": "...", "created": "...", "updated": "...", "messageCount": 2 },
286
- "taskState": { "goal": "...", "todos": [{ "id": 1, "text": "...", "status": "in_progress" }], "nextId": 2 },
287
- "messages": [...]
288
- }
289
- }
290
- ```
291
-
292
- ## `POST /v1/sessions/:id/rename`
293
-
294
- ```json
295
- // 请求
296
- { "title": "new title" }
297
- // 响应
298
- { "ok": true, "session_id": "abc", "title": "new title" }
299
- ```
300
-
301
- ## `POST /v1/chat/undo`
302
-
303
- ```json
304
- // 请求
305
- { "session_id": "abc123" }
306
- // 响应
307
- { "ok": true, "message_count": 3, "messages": [...] }
308
- ```
309
-
310
- 截断到最后一条 user 消息（保留该消息，删除其后的 assistant/tool 消息）。
311
-
312
- ## `POST /v1/chat/redo`
313
-
314
- 取出会话中最后一条用户文本，追加一轮后再跑。请求体与 `/v1/chat` 相同的可选字段（`stream`、`model`、`provider`、`plan_mode`、`auto_approve`、采样参数），`session_id` 必填。
315
-
316
- ```json
317
- // 请求
318
- { "session_id": "abc123", "stream": false }
319
- ```
320
-
321
- 没有用户文本时返回 `400 no_user_message`。
322
-
323
- ## `GET /v1/budget`
324
-
325
- ```json
326
- { "maxCostUSD": 5, "source": "global" }
327
- ```
328
-
329
- `source` 为 `project`、`global` 或 `null`（未设置）。`maxCostUSD` 为合并后的生效值。
330
-
331
- ## `POST /v1/budget`
332
-
333
- ```json
334
- // 请求
335
- { "maxCostUSD": 8, "scope": "project" }
336
- // 响应
337
- { "ok": true, "maxCostUSD": 8, "source": "project", "scope": "project" }
338
- ```
339
-
340
- `scope` 省略时写入全局。`maxCostUSD` 必须为正数。
341
-
342
- ## `GET /v1/permission`
343
-
344
- ```json
345
- { "permission": "accept-edits", "source": null, "label": "accept edits" }
346
- ```
347
-
348
- `permission` 为 `ask` / `accept-edits` / `allow-all`。`source` 为 `cli`、`project`、`global` 或 `null`（使用默认：`accept-edits`，自动允许文件修改）。
349
-
350
- ## `POST /v1/permission`
351
-
352
- ```json
353
- // 请求
354
- { "permission": "accept-edits", "scope": "project" }
355
- // 响应
356
- { "ok": true, "scope": "project", "permission": "accept-edits", "source": "project", "label": "自动允许改文件" }
357
- ```
358
-
359
- `scope` 省略时写入全局。`permission` 必须为 `ask` / `accept-edits` / `allow-all`。
360
-
361
- ## `GET /v1/thinking`
362
-
363
- ```json
364
- { "thinking": "max", "source": "global", "label": "max" }
365
- ```
366
-
367
- `thinking` 为 `off` / `low` / `medium` / `high` / `max`。未配置时为 `medium`，`source` 为 `null`。已配置时 `source` 为 `cli`、`project` 或 `global`。
368
-
369
- ## `POST /v1/thinking`
370
-
371
- ```json
372
- { "thinking": "max", "scope": "project" }
373
- ```
374
- ```json
375
- { "ok": true, "scope": "project", "thinking": "max", "source": "project", "label": "max" }
376
- ```
377
-
378
- `scope` 省略时写入全局，并清除项目配置里的 `thinking` 覆盖，避免旧的项目值（例如 `off`）在重启后继续生效。`thinking` 必须为 `off` / `low` / `medium` / `high` / `max`（`none` → `off`，`xhigh` / `extra-high` → `max`）。
379
-
380
- ## `GET /v1/sandbox`
381
-
382
- ```json
383
- { "mode": "off", "network": "allow", "extraWriteRoots": [], "extraReadRoots": [], "source": null, "label": "未隔离，允许联网" }
384
- ```
385
-
386
- `source` 为 `cli`、`env`、`project`、`global` 或 `null`（使用默认：不隔离）。未配置时 `mode` 为 `off`。
387
-
388
- ## `POST /v1/sandbox`
389
-
390
- ```json
391
- // 请求
392
- { "mode": "workspace", "network": "deny", "scope": "project" }
393
- // 响应
394
- { "ok": true, "scope": "project", "mode": "workspace", "network": "deny", "extraWriteRoots": [], "extraReadRoots": [], "source": "project", "label": "工作区隔离，禁止联网" }
395
- ```
396
-
397
- `scope` 省略时写入全局。至少提供 `mode`、`network`、`extraWriteRoots`、`extraReadRoots` 之一。`mode` 为 `off` / `workspace` / `strict`；`network` 为 `allow` / `deny`。
398
-
399
- ## `GET /v1/diff`
400
-
401
- ```json
402
- { "ok": true, "diff": "..." }
403
- ```
404
-
405
- 非 git 仓库或无变更时仍返回 200：`{ "ok": false, "reason": "not_git"|"no_changes"|"error", "message": "..." }`。
406
-
407
- ## `POST /v1/approvals`
408
-
409
- 配合 SSE `confirm` 事件。
410
-
411
- ```json
412
- // 请求
413
- { "id": "…", "accepted": true }
414
- // 响应
415
- { "ok": true, "id": "…", "accepted": true }
416
- ```
417
-
418
- 未知 id 返回 `404 unknown_approval_id`。
419
-
420
- ## `POST /v1/answers`
421
-
422
- 配合 SSE `question` 事件。`answer` 为 `null` 表示跳过。单选传选项原文或自定义文字；多选可传 JSON 字符串数组（如 `["A","自定义"]`），或单个字符串。
423
-
424
- ```json
425
- // 请求
426
- { "id": "…", "answer": "use bun" }
427
- ```
428
-
429
- 未知 id 返回 `404 unknown_answer_id`。
430
-
431
- ## `GET /v1/skills`
432
-
433
- ```json
434
- {
435
- "count": 2,
436
- "enabled_count": 1,
437
- "stale_disabled": ["removed-skill"],
438
- "skills": [
439
- {
440
- "name": "my-skill",
441
- "description": "What it does",
442
- "location": "/path/.min-agent/skills/my-skill/SKILL.md",
443
- "enabled": true,
444
- "version": "1.0.0",
445
- "allowed_tools": ["read"],
446
- "requires_bins": ["some-cli"]
447
- }
448
- ]
449
- }
450
- ```
451
-
452
- 禁用项额外带 `disabled_scope`（`global` 或 `project`）。
453
- 随包装载的技能额外带 `builtin: true`；会话开始即注入正文的技能额外带 `always_load: true`（内置 `self-config` 即如此）。
454
- `stale_disabled` 列出两个范围的 `disabledSkills` 中没有对应技能的名字（拼写错误或技能已删除）。
455
-
456
- ## `GET /v1/skills/:name`
457
-
458
- 返回单个技能，附带 `content`（SKILL.md 正文）。技能不存在返回 404 `{ "error": "skill_not_found", "available": [...] }`。
459
-
460
- ## `POST /v1/skills/reload`
461
-
462
- 重新扫描技能目录（新增/修改 SKILL.md 后无需重启服务）。
463
-
464
- ```json
465
- { "ok": true, "count": 2, "enabled_count": 1, "stale_disabled": [], "skills": [...] }
466
- ```
467
-
468
- ## `POST /v1/skills/:name/enable` / `/disable`
469
-
470
- 请求体可选：
471
-
472
- ```json
473
- { "scope": "project" }
474
- ```
475
-
476
- `scope` 为 `global`（默认，写 `~/.min-agent/config.json`）或 `project`（写 `.min-agent/config.json`）。项目范围优先于全局，因此全局禁用的技能可以在单个项目里用 `{"scope":"project"}` 的 enable 重新启用。
477
-
478
- ```json
479
- { "ok": true, "name": "my-skill", "enabled": false, "scope": "project" }
480
- ```
481
-
482
- 若改动被另一范围覆盖，响应带 `blocked_by`（`global` 或 `project`），`enabled` 反映实际生效状态。
483
- 技能不存在返回 404 `{ "error": "skill_not_found", "available": [...] }`；`scope` 非法返回 400 `{ "error": "invalid_scope" }`。
484
-
485
- ## `POST /v1/mcp/:name/enable` / `/disable`
486
-
487
- 请求体可选：
488
-
489
- ```json
490
- { "scope": "project" }
491
- ```
492
-
493
- `scope` 为 `global`（默认，写 `~/.min-agent/mcp.json`）或 `project`（写 `.min-agent/mcp.json`）。服务器在另一范围时返回 404 并带 `hint`。
494
-
495
- ```json
496
- { "ok": true, "name": "fs", "enabled": true, "scope": "global", "connected": true }
497
- ```
498
-
499
- ## `GET /v1/cost`
500
-
501
- | 参数 | 说明 |
502
- |------|------|
503
- | `model` | 模型 ID（默认配置默认模型） |
504
- | `input` | 输入 token 数 |
505
- | `output` | 输出 token 数 |
506
-
507
- ```json
508
- { "model": "gpt-4o", "price": { "inputPerMillion": 2.5, "outputPerMillion": 10 }, "cost_usd": 7.5 }
509
- ```
510
-
511
- ## `POST /v1/chat/reload-instructions`
512
-
513
- ```json
514
- { "ok": true, "instructions_chars": 1234 }
515
- ```
516
-
517
- ---
518
-
519
- ## `GET /v1/sessions`
520
-
521
- ```json
522
- { "sessions": [{ "id": "abc", "title": "Fix bug", "updated": "...", "messageCount": 12 }] }
523
- ```
524
-
525
- ## `DELETE /v1/sessions/:id`
526
-
527
- ```json
528
- { "ok": true, "deleted": "abc123" }
529
- ```
530
-
531
- ---
532
-
533
- ## `GET /v1/memory`
534
-
535
- ```json
536
- {
537
- "memory": "off",
538
- "source": null,
539
- "label": "off",
540
- "memories": [{ "content": "...", "tags": [...], "created": "..." }],
541
- "project_memories": [{ "content": "...", "tags": [...], "created": "..." }]
542
- }
543
- ```
544
-
545
- `memories` 始终为全局；`project_memories` 为当前目录 `.min-agent/memory.json`。`memory` 为 `on` / `off`。未配置时为 `off`，`source` 为 `null`。已配置时 `source` 为 `cli`、`project` 或 `global`。关闭时仍可读写条目，但对话不会注入记忆，也不会暴露 memory 工具。
546
-
547
- ## `GET /v1/memory/mode`
548
-
549
- ```json
550
- { "memory": "off", "source": null, "label": "off" }
551
- ```
552
-
553
- ## `POST /v1/memory/mode`
554
-
555
- ```json
556
- { "memory": "on", "scope": "project" }
557
- ```
558
-
559
- ```json
560
- { "ok": true, "scope": "project", "memory": "on", "source": "project", "label": "on" }
561
- ```
562
-
563
- `scope` 省略时写入全局，并清除项目配置里的 `memory` 覆盖。`memory` 必须为 `on` / `off`（`true` / `enable` → `on`，`false` / `disable` → `off`）。
564
-
565
- ## `POST /v1/memory`
566
-
567
- ```json
568
- // 请求
569
- { "content": "prefer TypeScript", "tags": ["preference"], "scope": "project" }
570
- // 响应
571
- { "ok": true, "memory": {...}, "scope": "project" }
572
- ```
573
-
574
- `scope` 省略时写入全局（兼容旧客户端）。非法值返回 `400 invalid_scope`。
575
-
576
- ## `GET /v1/memory/search?q=typescript`
577
-
578
- 可选 `scope=global|project`。省略时两个商店都搜。
579
-
580
- ```json
581
- {
582
- "results": [{ "content": "...", "tags": [...], "index": 0 }],
583
- "project_results": []
584
- }
585
- ```
586
-
587
- ## `DELETE /v1/memory/:index`
588
-
589
- 可选 `?scope=project`；默认全局。索引从 1 开始，按对应商店编号。
590
-
591
- ```json
592
- { "ok": true, "deleted": 1, "scope": "global" }
593
- ```
594
-
595
- ---
596
-
597
- ## `GET /v1/mcp`
598
-
599
- ```json
600
- {
601
- "servers": {
602
- "filesystem": { "connected": true, "enabled": true, "tools": ["read_file", "write_file"], "resource_count": 2, "prompt_count": 1 },
603
- "broken": { "connected": false, "enabled": true, "tools": [], "resource_count": 0, "prompt_count": 0, "error": "connection timed out after 30000ms" }
604
- }
605
- }
606
- ```
607
-
608
- `resource_count` / `prompt_count` 为连接时缓存的数量。未声明 resources/prompts 的服务器为 0。
609
-
610
- ## `GET /v1/mcp/:name/resources`
611
-
612
- ```json
613
- {
614
- "name": "filesystem",
615
- "resources": [{ "uri": "file:///tmp/a.txt", "name": "a.txt", "mimeType": "text/plain" }],
616
- "templates": [{ "uriTemplate": "file:///{path}", "name": "file" }]
617
- }
618
- ```
619
-
620
- 未配置返回 `404 mcp_not_found`；已配置但未连接返回 `404 mcp_not_connected`。
621
-
622
- ## `GET /v1/mcp/:name/prompts`
623
-
624
- ```json
625
- {
626
- "name": "docs",
627
- "prompts": [{ "name": "review", "description": "Review a file", "arguments": [{ "name": "path", "required": true }] }]
628
- }
629
- ```
630
-
631
- ## `POST /v1/mcp/:name/resources/read`
632
-
633
- ```json
634
- // 请求
635
- { "uri": "file:///tmp/a.txt" }
636
- // 响应
637
- { "ok": true, "name": "filesystem", "uri": "file:///tmp/a.txt", "content": "..." }
638
- ```
639
-
640
- ## `POST /v1/mcp/:name/prompts/get`
641
-
642
- ```json
643
- // 请求
644
- { "prompt": "review", "arguments": { "path": "src/a.ts" } }
645
- // 响应
646
- { "ok": true, "name": "docs", "prompt": "review", "content": "user: ..." }
647
- ```
648
-
649
- ## `POST /v1/mcp`
650
-
651
- 添加或覆盖一个 MCP 服务器。保存后立即重连（`sync`），响应带实时状态。
652
-
653
- ```json
654
- // 本地 stdio
655
- { "name": "fs", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
656
- // 本地 stdio（字符串 + args）
657
- { "name": "fs", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
658
- // 远程
659
- { "name": "remote", "url": "https://mcp.example.com", "token": "xxx", "remoteTransport": "sse" }
660
- // 项目范围（写 .min-agent/mcp.json）
661
- { "name": "fs", "command": ["..."], "project": true }
662
- ```
663
-
664
- 支持的字段：`name`（必填）、`command`（数组或字符串）、`args`、`url`、`token`、`headers`、`environment`、`remoteTransport`（`streamable-http`/`sse`/`auto`，非法值返回 400）、`timeout`、`connectTimeout`、`callTimeout`、`enabled`、`project`。
665
-
666
- ```json
667
- { "ok": true, "name": "fs", "scope": "global", "connected": true, "tools": ["read_file"] }
668
- ```
669
-
670
- ## `DELETE /v1/mcp/:name`
671
-
672
- `?project=1` 删除项目范围（`.min-agent/mcp.json`）的条目；默认全局。服务器在另一范围时返回 404 并带 `hint`。
673
-
674
- ```json
675
- { "ok": true, "deleted": "fs", "scope": "global" }
676
- ```
677
-
678
- ---
679
-
680
- ## `GET /v1/rules`
681
-
682
- ```json
683
- { "count": 2, "rules": [{ "source": "~/.min-agent/rules.md", "chars": 456 }] }
684
- ```
685
-
686
- ---
687
-
688
- ## 错误码
689
-
690
- | 状态 | 说明 |
691
- |------|------|
692
- | 400 | 请求参数错误 / JSON 解析失败（`invalid_json`） |
693
- | 401 | 未授权 |
694
- | 404 | 资源不存在 |
695
- | 408 | 请求体读取超时（`payload_timeout`，30s） |
696
- | 413 | 请求体过大（>2MB，`payload_too_large`） |
697
- | 415 | Content-Type 不是 JSON |
698
- | 500 | 内部错误 |
699
-
700
- ---
701
-
702
- ## 示例
703
-
704
- ```bash
705
- # 对话
706
- curl http://127.0.0.1:8787/v1/chat \
707
- -H "Content-Type: application/json" \
708
- -d '{"message":"list files"}'
709
-
710
- # 流式
711
- curl -N http://127.0.0.1:8787/v1/chat \
712
- -H "Content-Type: application/json" \
713
- -d '{"message":"say hi","stream":true}'
714
-
715
- # 兼容路径 /v1/code
716
- curl http://127.0.0.1:8787/v1/code \
717
- -H "Content-Type: application/json" \
718
- -d '{"message":"add error handling to login"}'
719
-
720
- # 图片
721
- curl http://127.0.0.1:8787/v1/paste \
722
- -H "Content-Type: application/json" \
723
- -d '{"image_base64":"iVBOR...","message":"分析这张图"}'
724
-
725
- # 添加 MCP
726
- curl -X POST http://127.0.0.1:8787/v1/mcp \
727
- -H "Content-Type: application/json" \
728
- -d '{"name":"fs","command":["npx","-y","@modelcontextprotocol/server-filesystem","/tmp"]}'
729
-
730
- # 添加记忆
731
- curl -X POST http://127.0.0.1:8787/v1/memory \
732
- -H "Content-Type: application/json" \
733
- -d '{"content":"prefer TypeScript","tags":["preference"]}'
734
-
735
- # 设置项目预算
736
- curl -X POST http://127.0.0.1:8787/v1/budget \
737
- -H "Content-Type: application/json" \
738
- -d '{"maxCostUSD":5,"scope":"project"}'
739
-
740
- # 设置确认模式
741
- curl -X POST http://127.0.0.1:8787/v1/permission \
742
- -H "Content-Type: application/json" \
743
- -d '{"permission":"accept-edits","scope":"project"}'
744
-
745
- # 启用工作区隔离
746
- curl -X POST http://127.0.0.1:8787/v1/sandbox \
747
- -H "Content-Type: application/json" \
748
- -d '{"mode":"workspace","scope":"project"}'
749
-
750
- # 查看工作区变更
751
- curl http://127.0.0.1:8787/v1/diff
752
-
753
- # 压缩会话
754
- curl -X POST http://127.0.0.1:8787/v1/chat/compact \
755
- -H "Content-Type: application/json" \
756
- -d '{"session_id":"abc123"}'
757
- ```