min-agent 0.2.1 → 0.4.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，防止路径穿越。
+
 ---
 
 ## 端点一览
@@ -24,25 +30,50 @@ min-agent serve --host 0.0.0.0 --port 3000
 |------|------|------|
 | GET | `/health` | 存活检查 |
 | GET | `/v1/meta` | 运行环境 |
+| GET | `/v1/update` | 检查 npm 是否有新版本（不执行安装） |
 | GET | `/v1/models` | 模型列表 |
 | GET | `/v1/context` | 上下文窗口信息 |
 | GET | `/v1/project` | 项目扫描 |
-| POST | `/v1/chat` | 对话 |
-| POST | `/v1/code` | Code 模式对话 |
+| POST | `/v1/chat` | 对话（项目感知） |
+| POST | `/v1/code` | 与 `/v1/chat` 相同（兼容路径） |
 | POST | `/v1/paste` | 图片+文本对话 |
 | POST | `/v1/chat/compact` | 手动压缩会话 |
 | POST | `/v1/chat/reload-instructions` | 重载规则 |
+| POST | `/v1/chat/redo` | 重发会话最后一条用户消息 |
 | GET | `/v1/sessions` | 列出会话 |
 | DELETE | `/v1/sessions/:id` | 删除会话 |
-| GET | `/v1/memory` | 列出记忆 |
+| GET | `/v1/memory` | 列出记忆（含 `project_memories`） |
 | POST | `/v1/memory` | 添加记忆 |
 | GET | `/v1/memory/search?q=xxx` | 搜索记忆 |
 | DELETE | `/v1/memory/:index` | 删除记忆 |
+| GET | `/v1/budget` | 当前预算上限 |
+| POST | `/v1/budget` | 设置预算上限 |
+| GET | `/v1/permission` | 当前确认模式 |
+| POST | `/v1/permission` | 设置确认模式 |
+| GET | `/v1/sandbox` | 当前隔离策略 |
+| POST | `/v1/sandbox` | 设置隔离策略 |
+| GET | `/v1/diff` | 工作区未提交变更 |
+| POST | `/v1/approvals` | 回答危险操作确认 |
+| POST | `/v1/answers` | 回答代理提问 |
 | GET | `/v1/mcp` | MCP 状态 |
+| GET | `/v1/mcp/:name/resources` | 列出资源与 URI 模板 |
+| GET | `/v1/mcp/:name/prompts` | 列出 prompt 模板 |
+| POST | `/v1/mcp/:name/resources/read` | 读取一条资源 |
+| POST | `/v1/mcp/:name/prompts/get` | 填充一条 prompt |
 | 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` | 模型价格与成本估算 |
 
 ---
 
@@ -55,9 +86,25 @@ 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 }
+{ "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": "询问确认" } }
 ```
 
+## `GET /v1/update`
+
+查询当前运行版本与 npm 上的最新版本。此接口只检查，不会执行 `npm install`。
+
+```json
+{ "current": "0.3.0", "latest": "0.3.1", "update_available": true }
+```
+
+无法访问 npm registry 时：
+
+```json
+{ "current": "0.3.0", "latest": null, "update_available": false, "error": "registry_unavailable" }
+```
+
+CLI 升级请使用 `min-agent update`（执行 `npm install -g min-agent`）。
+
 ## `GET /v1/models`
 
 ```json
@@ -67,9 +114,11 @@ min-agent serve --host 0.0.0.0 --port 3000
 ## `GET /v1/context`
 
 ```json
-{ "context_window": 128000, "model": "gpt-4o" }
+{ "context_window": 1000000, "source": "config", "model": "gpt-4o" }
 ```
 
+`source` 为 `config`（配置中的 `contextWindow`）、`detected`（从接口读到）或 `fallback`（未读到，按 512k 处理）。
+
 ## `GET /v1/project`
 
 ```json
@@ -97,9 +146,21 @@ 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 | 核采样参数 |
+| `plan_mode` | boolean | 只读计划模式（去掉写入类工具） |
+| `auto_approve` | boolean | 默认 `true`。设为 `false` 时必须 `stream: true`，并通过 `POST /v1/approvals` / `POST /v1/answers` 回调 |
+| `sandbox` | string | 本轮隔离：`off` / `workspace` / `strict`。只能比服务当前策略更严，不能放宽 |
+| `network` | string | 本轮联网：`allow` / `deny`。`deny` 只能收紧 |
+
+`auto_approve: false` 且未开流式时返回 `400 auto_approve_requires_stream`。确认/提问最多等待 5 分钟，超时视为拒绝或跳过。客户端断开连接时未完成的确认视为拒绝。
+
+`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`）。
 
 ### 非流式响应
 
@@ -112,11 +173,23 @@ min-agent serve --host 0.0.0.0 --port 3000
   "session_id": "abc123",
   "step_count": 2,
   "usage": { "inputTokens": 1200, "outputTokens": 300 },
+  "context_tokens": 1200,
   "has_error": false,
-  "aborted": false
+  "aborted": false,
+  "max_steps_reached": false,
+  "incomplete": false,
+  "budget_exceeded": false,
+  "continues": 0,
+  "stopped": false,
+  "empty_response": false,
+  "empty_attempts": 0,
+  "task_state": { "goal": "...", "todos": [], "nextId": 1 },
+  "project": { "languages": [...], "directory": "...", "...": "..." }
 }
 ```
 
+`usage` 为本轮各次模型请求的 token 合计（计费口径；多步工具调用会把每次请求的 input 加总）。`context_tokens` 为最近一次请求占用的上下文大小，用来衡量窗口占用，不要把 `usage.inputTokens` 当占用百分比的分子。
+
 ### 流式 SSE 事件
 
 | type | 字段 | 说明 |
@@ -126,20 +199,18 @@ min-agent serve --host 0.0.0.0 --port 3000
 | `tool_call` | name, input | 工具调用 |
 | `tool_result` | name, output | 工具返回 |
 | `compaction` | line | 压缩进度 |
+| `notice` | kind, attempt, max_attempts, delay_ms | 提示（目前只有 `kind: "empty_response"`，表示 provider 返回空流后即将重发同一请求） |
 | `error` | message | 错误 |
-| `done` | step_count, usage, messages, session_id | 结束 |
+| `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}`）会先被规范成字符串再下发 |
 | `fatal` | message | 致命错误 |
 
 ---
 
 ## `POST /v1/code`
 
-Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/chat` 相同。
-
-响应额外包含：
-```json
-{ "mode": "code", "project": { "languages": [...], ... }, ... }
-```
+与 `/v1/chat` 相同的兼容路径。请求体与响应结构一致（含 `project`）。
 
 ---
 
@@ -153,8 +224,20 @@ 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 流式 |
+| `temperature` | number | 采样温度 |
+| `maxTokens` | number | 最大输出 token 数 |
+| `topP` | number | 核采样参数 |
+| `plan_mode` | boolean | 只读计划模式 |
+| `auto_approve` | boolean | 同 `/v1/chat` |
+
+`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` 非流式响应结构一致。
+
+`session_id` 不存在时返回 `404 session_not_found`（与 `/v1/chat` 一致）。
+
+非流式响应与 `/v1/chat` 相同，始终包含 `project`。请求里多传 `code` 会被忽略。
 
 ---
 
@@ -167,6 +250,218 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 { "ok": true, "compacted": true, "message_count": 5 }
 ```
 
+## `GET /v1/sessions/:id`
+
+```json
+{
+  "session": {
+    "meta": { "id": "abc", "title": "...", "created": "...", "updated": "...", "messageCount": 2 },
+    "taskState": { "goal": "...", "todos": [{ "id": 1, "text": "...", "status": "in_progress" }], "nextId": 2 },
+    "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 消息）。
+
+## `POST /v1/chat/redo`
+
+取出会话中最后一条用户文本，追加一轮后再跑。请求体与 `/v1/chat` 相同的可选字段（`stream`、`model`、`provider`、`plan_mode`、`auto_approve`、采样参数），`session_id` 必填。
+
+```json
+// 请求
+{ "session_id": "abc123", "stream": false }
+```
+
+没有用户文本时返回 `400 no_user_message`。
+
+## `GET /v1/budget`
+
+```json
+{ "maxCostUSD": 5, "source": "global" }
+```
+
+`source` 为 `project`、`global` 或 `null`（未设置）。`maxCostUSD` 为合并后的生效值。
+
+## `POST /v1/budget`
+
+```json
+// 请求
+{ "maxCostUSD": 8, "scope": "project" }
+// 响应
+{ "ok": true, "maxCostUSD": 8, "source": "project", "scope": "project" }
+```
+
+`scope` 省略时写入全局。`maxCostUSD` 必须为正数。
+
+## `GET /v1/permission`
+
+```json
+{ "permission": "ask", "source": null, "label": "询问确认" }
+```
+
+`permission` 为 `ask` / `accept-edits` / `allow-all`。`source` 为 `cli`、`project`、`global` 或 `null`（使用默认：询问确认）。
+
+## `POST /v1/permission`
+
+```json
+// 请求
+{ "permission": "accept-edits", "scope": "project" }
+// 响应
+{ "ok": true, "scope": "project", "permission": "accept-edits", "source": "project", "label": "自动允许改文件" }
+```
+
+`scope` 省略时写入全局。`permission` 必须为 `ask` / `accept-edits` / `allow-all`。
+
+## `GET /v1/sandbox`
+
+```json
+{ "mode": "off", "network": "allow", "extraWriteRoots": [], "extraReadRoots": [], "source": null, "label": "未隔离，允许联网" }
+```
+
+`source` 为 `cli`、`env`、`project`、`global` 或 `null`（使用默认：不隔离）。未配置时 `mode` 为 `off`。
+
+## `POST /v1/sandbox`
+
+```json
+// 请求
+{ "mode": "workspace", "network": "deny", "scope": "project" }
+// 响应
+{ "ok": true, "scope": "project", "mode": "workspace", "network": "deny", "extraWriteRoots": [], "extraReadRoots": [], "source": "project", "label": "工作区隔离，禁止联网" }
+```
+
+`scope` 省略时写入全局。至少提供 `mode`、`network`、`extraWriteRoots`、`extraReadRoots` 之一。`mode` 为 `off` / `workspace` / `strict`；`network` 为 `allow` / `deny`。
+
+## `GET /v1/diff`
+
+```json
+{ "ok": true, "diff": "..." }
+```
+
+非 git 仓库或无变更时仍返回 200：`{ "ok": false, "reason": "not_git"|"no_changes"|"error", "message": "..." }`。
+
+## `POST /v1/approvals`
+
+配合 SSE `confirm` 事件。
+
+```json
+// 请求
+{ "id": "…", "accepted": true }
+// 响应
+{ "ok": true, "id": "…", "accepted": true }
+```
+
+未知 id 返回 `404 unknown_approval_id`。
+
+## `POST /v1/answers`
+
+配合 SSE `question` 事件。`answer` 为 `null` 表示跳过。
+
+```json
+// 请求
+{ "id": "…", "answer": "use bun" }
+```
+
+未知 id 返回 `404 unknown_answer_id`。
+
+## `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`）。
+随包装载的技能额外带 `builtin: true`；会话开始即注入正文的技能额外带 `always_load: true`（内置 `self-config` 即如此）。
+`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
@@ -192,28 +487,42 @@ Code 模式对话（项目感知 prompt + explore 工具）。请求体与 `/v1/
 ## `GET /v1/memory`
 
 ```json
-{ "memories": [{ "content": "...", "tags": [...], "created": "..." }] }
+{
+  "memories": [{ "content": "...", "tags": [...], "created": "..." }],
+  "project_memories": [{ "content": "...", "tags": [...], "created": "..." }]
+}
 ```
 
+`memories` 始终为全局；`project_memories` 为当前目录 `.min-agent/memory.json`。
+
 ## `POST /v1/memory`
 
 ```json
 // 请求
-{ "content": "prefer TypeScript", "tags": ["preference"] }
+{ "content": "prefer TypeScript", "tags": ["preference"], "scope": "project" }
 // 响应
-{ "ok": true, "memory": {...} }
+{ "ok": true, "memory": {...}, "scope": "project" }
 ```
 
+`scope` 省略时写入全局（兼容旧客户端）。非法值返回 `400 invalid_scope`。
+
 ## `GET /v1/memory/search?q=typescript`
 
+可选 `scope=global|project`。省略时两个商店都搜。
+
 ```json
-{ "results": [{ "content": "...", "tags": [...], "index": 0 }] }
+{
+  "results": [{ "content": "...", "tags": [...], "index": 0 }],
+  "project_results": []
+}
 ```
 
 ## `DELETE /v1/memory/:index`
 
+可选 `?scope=project`；默认全局。索引从 1 开始，按对应商店编号。
+
 ```json
-{ "ok": true, "deleted": 1 }
+{ "ok": true, "deleted": 1, "scope": "global" }
 ```
 
 ---
@@ -221,36 +530,86 @@ 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"], "resource_count": 2, "prompt_count": 1 },
+    "broken": { "connected": false, "enabled": true, "tools": [], "resource_count": 0, "prompt_count": 0, "error": "connection timed out after 30000ms" }
+  }
+}
+```
+
+`resource_count` / `prompt_count` 为连接时缓存的数量。未声明 resources/prompts 的服务器为 0。
+
+## `GET /v1/mcp/:name/resources`
+
+```json
+{
+  "name": "filesystem",
+  "resources": [{ "uri": "file:///tmp/a.txt", "name": "a.txt", "mimeType": "text/plain" }],
+  "templates": [{ "uriTemplate": "file:///{path}", "name": "file" }]
+}
+```
+
+未配置返回 `404 mcp_not_found`；已配置但未连接返回 `404 mcp_not_connected`。
+
+## `GET /v1/mcp/:name/prompts`
+
+```json
+{
+  "name": "docs",
+  "prompts": [{ "name": "review", "description": "Review a file", "arguments": [{ "name": "path", "required": true }] }]
+}
+```
+
+## `POST /v1/mcp/:name/resources/read`
+
+```json
+// 请求
+{ "uri": "file:///tmp/a.txt" }
+// 响应
+{ "ok": true, "name": "filesystem", "uri": "file:///tmp/a.txt", "content": "..." }
+```
+
+## `POST /v1/mcp/:name/prompts/get`
+
+```json
+// 请求
+{ "prompt": "review", "arguments": { "path": "src/a.ts" } }
+// 响应
+{ "ok": true, "name": "docs", "prompt": "review", "content": "user: ..." }
 ```
 
 ## `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 +622,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 | 内部错误 |
 
@@ -285,7 +645,7 @@ curl -N http://127.0.0.1:8787/v1/chat \
   -H "Content-Type: application/json" \
   -d '{"message":"say hi","stream":true}'
 
-# Code 模式
+# 兼容路径 /v1/code
 curl http://127.0.0.1:8787/v1/code \
   -H "Content-Type: application/json" \
   -d '{"message":"add error handling to login"}'
@@ -305,6 +665,24 @@ curl -X POST http://127.0.0.1:8787/v1/memory \
   -H "Content-Type: application/json" \
   -d '{"content":"prefer TypeScript","tags":["preference"]}'
 
+# 设置项目预算
+curl -X POST http://127.0.0.1:8787/v1/budget \
+  -H "Content-Type: application/json" \
+  -d '{"maxCostUSD":5,"scope":"project"}'
+
+# 设置确认模式
+curl -X POST http://127.0.0.1:8787/v1/permission \
+  -H "Content-Type: application/json" \
+  -d '{"permission":"accept-edits","scope":"project"}'
+
+# 启用工作区隔离
+curl -X POST http://127.0.0.1:8787/v1/sandbox \
+  -H "Content-Type: application/json" \
+  -d '{"mode":"workspace","scope":"project"}'
+
+# 查看工作区变更
+curl http://127.0.0.1:8787/v1/diff
+
 # 压缩会话
 curl -X POST http://127.0.0.1:8787/v1/chat/compact \
   -H "Content-Type: application/json" \