min-agent 0.1.4 → 0.1.5

package/docs/API.md

@@ -1,216 +1,403 @@
 # min-agent HTTP API
 
-通过 `min-agent serve` 启动本地 HTTP 服务，以编程方式调用与 CLI `chat` 相同的代理能力（同一套 MCP、技能、规则、工具与模型配置）。
+通过 `min-agent serve` 启动本地 HTTP 服务，以编程方式调用与 CLI 相同的代理能力。
 
 ## 启动
 
 ```bash
 min-agent serve
 min-agent serve --host 127.0.0.1 --port 8787
-min-agent serve -p 3030
 ```
 
-环境变量（可选）：
+环境变量：
 
 | 变量 | 说明 |
 |------|------|
-| `MIN_AGENT_SERVE_HOST` | 默认监听地址，默认 `127.0.0.1` |
-| `MIN_AGENT_SERVE_PORT` | 默认端口，默认 `8787` |
-| `MIN_AGENT_SERVE_TOKEN` | 若设置，则所有除 `OPTIONS` 外的请求须带 `Authorization: Bearer <token>` |
-| `MIN_AGENT_SERVE_CORS` | 设为 `1` 或 `true` 时添加 `Access-Control-Allow-Origin: *`（仅开发跨域时使用） |
-
-启动后进程内 **`--yes` 等效**：危险 shell 等确认会自动通过，请勿把未鉴权服务暴露到公网。
+| `MIN_AGENT_SERVE_HOST` | 监听地址（默认 `127.0.0.1`） |
+| `MIN_AGENT_SERVE_PORT` | 端口（默认 `8787`） |
+| `MIN_AGENT_SERVE_TOKEN` | 设置后所有请求须带 `Authorization: Bearer <token>` |
+| `MIN_AGENT_SERVE_CORS` | 设为 `1` 启用 CORS |
 
 ---
 
-## 通用约定
+## 端点一览
 
-- **Base URL**：`http://<host>:<port>`
-- **请求体**：JSON，`Content-Type: application/json`
-- **响应体**：JSON，除非注明为 SSE
-- **工作目录**：与启动 `serve` 时的 `process.cwd()` 一致（影响 `read`/`bash` 等工具路径）
-- **单例初始化**：进程启动时连接 MCP、扫描技能并加载规则；之后请求复用该状态。修改规则文件后可调用下方「重载规则」接口或重启进程
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/health` | 存活检查 |
+| GET | `/v1/meta` | 运行环境摘要 |
+| GET | `/v1/models` | 模型列表 |
+| GET | `/v1/context` | 上下文窗口信息 |
+| GET | `/v1/project` | 项目扫描（code 模式） |
+| POST | `/v1/chat` | 对话（支持流式） |
+| POST | `/v1/paste` | 粘贴图片 + 文本对话 |
+| POST | `/v1/code` | Code 模式对话（项目感知） |
+| POST | `/v1/chat/compact` | 手动压缩会话 |
+| POST | `/v1/chat/reload-instructions` | 重载规则 |
+| GET | `/v1/sessions` | 列出历史会话 |
+| DELETE | `/v1/sessions/:id` | 删除会话 |
+| GET | `/v1/memory` | 列出记忆 |
+| POST | `/v1/memory` | 添加记忆 |
+| GET | `/v1/memory/search?q=xxx` | 搜索记忆 |
+| DELETE | `/v1/memory/:index` | 删除记忆 |
+| GET | `/v1/mcp` | MCP 服务器状态 |
+| POST | `/v1/mcp` | 添加 MCP 服务器 |
+| DELETE | `/v1/mcp/:name` | 删除 MCP 服务器 |
+| GET | `/v1/skills` | 可用技能列表 |
+| GET | `/v1/rules` | 已加载的规则 |
 
 ---
 
 ## `GET /health`
 
-存活检查。
+```json
+{ "ok": true, "service": "min-agent", "version": "0.1.0" }
+```
+
+---
 
-**响应 200**
+## `GET /v1/meta`
+
+```json
+{ "version": "0.1.0", "cwd": "/path/to/project", "instructions_chars": 1234 }
+```
+
+---
+
+## `GET /v1/models`
+
+```json
+{ "default_model": "gpt-4o", "models": ["gpt-4o", "gpt-4o-mini", "..."] }
+```
+
+---
+
+## `GET /v1/context`
+
+返回当前模型的上下文窗口大小（自动检测）。
+
+```json
+{ "context_window": 128000, "model": "gpt-4o" }
+```
+
+---
+
+## `GET /v1/project`
+
+扫描当前工作目录的项目信息（与 `min-agent code` 启动时相同）。
 
 ```json
 {
-  "ok": true,
-  "service": "min-agent",
-  "version": "0.1.0"
+  "project": {
+    "directory": "/path/to/project",
+    "isGitRepo": true,
+    "branch": "main",
+    "languages": ["TypeScript"],
+    "framework": "Next.js",
+    "packageManager": "bun",
+    "entryFiles": ["src/index.ts"],
+    "configFiles": ["package.json", "tsconfig.json"],
+    "summary": "..."
+  }
 }
 ```
 
 ---
 
-## `GET /v1/meta`
+## `POST /v1/chat`
+
+### 请求体
 
-运行环境摘要。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `message` | string | 单轮用户消息 |
+| `messages` | array | 多轮 ModelMessage[]（与 `message` 二选一） |
+| `model` | string | 覆盖默认模型 |
+| `stream` | boolean | SSE 流式返回 |
+| `session_id` | string | 恢复历史会话并追加 |
+| `images` | string[] | 本地图片路径 |
 
-**响应 200**
+### 非流式响应
 
 ```json
 {
-  "version": "0.1.0",
-  "cwd": "/path/to/project",
-  "instructions_chars": 1234
+  "messages": [...],
+  "assistant": { "role": "assistant", "content": "..." },
+  "tool_calls": [{ "name": "bash", "input": {...} }],
+  "tool_results": [{ "name": "bash", "output": "..." }],
+  "session_id": "abc123",
+  "step_count": 2,
+  "usage": { "inputTokens": 1200, "outputTokens": 300 },
+  "has_error": false,
+  "aborted": false
 }
 ```
 
+### 流式 SSE 事件
+
+| type | 字段 | 说明 |
+|------|------|------|
+| `assistant` | text | 正文增量 |
+| `thinking` | text | 思考片段 |
+| `tool_call` | name, input | 工具调用 |
+| `tool_result` | name, output | 工具返回 |
+| `compaction` | line | 压缩进度 |
+| `error` | message | 错误 |
+| `done` | step_count, usage, messages, session_id | 结束 |
+| `fatal` | message | 致命错误 |
+
 ---
 
-## `GET /v1/models`
+## `POST /v1/chat/compact`
+
+手动压缩指定会话的上下文。
+
+```json
+// 请求
+{ "session_id": "abc123" }
+
+// 响应
+{ "ok": true, "compacted": true, "message_count": 5 }
+```
+
+---
+
+## `POST /v1/chat/reload-instructions`
+
+重新加载规则文件（不重启 MCP）。
+
+```json
+{ "ok": true, "instructions_chars": 1234 }
+```
+
+---
 
-从当前配置的 OpenAI 兼容提供商拉取模型列表（与 CLI `min-agent models` 同源）。
+## `GET /v1/sessions`
 
-**响应 200**
+列出所有保存的会话。
 
 ```json
 {
-  "default_model": "gpt-4.1",
-  "models": ["gpt-4.1", "gpt-4o-mini", "..."]
+  "sessions": [
+    { "id": "abc123", "title": "Fix login bug", "created": "...", "updated": "...", "messageCount": 12 }
+  ]
 }
 ```
 
 ---
 
-## `POST /v1/chat/reload-instructions`
+## `DELETE /v1/sessions/:id`
+
+删除指定会话。
+
+```json
+{ "ok": true, "deleted": "abc123" }
+```
+
+---
 
-重新从磁盘加载 `AGENTS.md`、规则与 `config.json` 中的 instructions 片段（不重启 MCP）。
+## `GET /v1/memory`
 
-**响应 200**
+列出所有记忆。
 
 ```json
 {
-  "ok": true,
-  "instructions_chars": 1234
+  "memories": [
+    { "content": "用户喜欢中文回复", "tags": ["偏好"], "created": "2025-01-01T00:00:00Z" }
+  ]
 }
 ```
 
 ---
 
-## `POST /v1/chat`
+## `POST /v1/memory`
 
-执行一轮或多轮对话（与 CLI 使用相同的 `streamText` + 工具集）。
+添加记忆。
 
-### 请求体字段
+```json
+// 请求
+{ "content": "项目使用 bun 作为包管理器", "tags": ["project"] }
 
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `message` | `string` | 单轮：用户消息文本。与 `messages` 二选一（会话续写见下） |
-| `messages` | `array` | 多轮：完整 `ModelMessage[]`（与 AI SDK 一致：`role` + `content`）。最后一轮通常为用户消息 |
-| `model` | `string` | 可选，覆盖默认模型 |
-| `stream` | `boolean` | 为 `true` 时使用 **SSE** 流式返回 |
-| `session_id` | `string` | 可选，从 `~/.min-agent/sessions/<id>.json` 恢复历史，并追加本条 `message` 为新用户轮 |
-| `images` | `string[]` | 可选，本地图片路径（相对 cwd 或绝对路径），须与顶层 `message` 一起使用，用于构造多模态用户消息 |
+// 响应
+{ "ok": true, "memory": { "content": "...", "tags": [...], "created": "..." } }
+```
 
-### 会话续写 `session_id`
+---
 
-- 请求体必须包含 **`message`**（新用户发言）
-- 服务端加载该会话已有 `messages`，追加新用户消息后调用模型，并在本轮结束后 **写回同一 `session_id`**
+## `GET /v1/memory/search?q=bun`
 
-### 非流式 `stream: false`（默认）
+搜索记忆。
 
-**响应 200**
+```json
+{ "results": [{ "content": "...", "tags": [...], "created": "...", "index": 0 }] }
+```
+
+---
+
+## `DELETE /v1/memory/:index`
+
+删除记忆（1-based index）。
+
+```json
+{ "ok": true, "deleted": 1 }
+```
+
+---
+
+## `GET /v1/mcp`
+
+MCP 服务器连接状态。
 
 ```json
 {
-  "messages": [ ... ],
-  "assistant": { "role": "assistant", "content": "..." },
-  "tool_calls": [{ "name": "bash", "input": { "command": "ls" } }],
-  "tool_results": [{ "name": "bash", "output": "..." }],
-  "session_id": "abc123",
-  "step_count": 2,
-  "usage": { "inputTokens": 1200, "outputTokens": 300, "totalTokens": 1500 },
-  "has_error": false,
-  "aborted": false
+  "servers": {
+    "filesystem": { "connected": true, "tools": ["read_file", "write_file", "list_dir"] },
+    "fetch": { "connected": false, "tools": [] }
+  }
 }
 ```
 
-- `messages`：已包含本轮助手回复（就地追加，与 CLI 行为一致）
-- `tool_results` 中单条输出过长时会被截断并附带说明后缀
-- 未使用 `session_id` 时 `session_id` 字段为 `undefined`/省略
+---
 
-### 流式 `stream: true`
+## `GET /v1/skills`
 
-- **Headers**：`Content-Type: text/event-stream`
-- **Body**：SSE，每条事件为一行 `data: <json>\n\n`
+可用技能列表。
 
-事件 `type` 取值：
+```json
+{
+  "skills": [
+    { "name": "git-workflow", "description": "Git workflow guide", "location": "/path/to/SKILL.md" }
+  ]
+}
+```
 
-| `type` | 字段 | 说明 |
-|--------|------|------|
-| `assistant` | `text` | 助手正文增量（已剥离思考块，与入库内容一致） |
-| `thinking` | `text` | 模型泄漏的思考片段（若存在） |
-| `tool_call` | `name`, `input` | 工具调用开始 |
-| `tool_result` | `name`, `output` | 工具返回（可能截断） |
-| `compaction` | `line` | 上下文压缩进度说明 |
-| `error` | `message` | 流内模型/鉴权类错误事件 |
-| `done` | `step_count`, `usage`, `has_error`, `aborted`, `messages`, `session_id?` | 本轮结束；之后连接关闭 |
-| `fatal` | `message` | 服务异常，随后关闭 |
+---
 
-客户端断开连接时会 **Abort** 正在进行的生成；若已有部分正文，仍可能写入 `messages` 中的 assistant（与 CLI Ctrl+C 行为对齐）。
+## `GET /v1/rules`
 
-### 错误 HTTP 状态
+已加载的规则来源。
 
-| 状态 | 说明 |
-|------|------|
-| `400` | JSON 无效或缺少 `message`/`messages` |
-| `401` | 配置了 `MIN_AGENT_SERVE_TOKEN` 但未携带合法 Bearer |
-| `404` | `session_id` 不存在 |
-| `413` | 请求体超过约 2MB |
-| `415` | 非 `application/json` |
-| `500` | 未配置提供商等内部错误 |
+```json
+{
+  "count": 2,
+  "rules": [
+    { "source": "~/.min-agent/rules.md", "chars": 456 },
+    { "source": "/project/AGENTS.md", "chars": 1200 }
+  ]
+}
+```
 
 ---
 
-## `OPTIONS *`
+## `POST /v1/paste`
+
+发送剪贴板图片 + 文本进行多模态对话。
+
+```json
+// 请求
+{
+  "image_base64": "<base64 encoded image>",
+  "mime_type": "image/png",
+  "message": "这张图片里是什么？",
+  "model": "gpt-4o",
+  "session_id": "abc123",
+  "stream": true
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `image_base64` | string | **必填** Base64 编码的图片数据 |
+| `mime_type` | string | 图片 MIME 类型（默认 `image/png`） |
+| `message` | string | 文本 prompt（默认 "What's in this image?"） |
+| `model` | string | 覆盖模型 |
+| `session_id` | string | 追加到已有会话 |
+| `stream` | boolean | SSE 流式 |
 
-当启用 `MIN_AGENT_SERVE_CORS` 时，用于浏览器预检；返回 `204`。
+响应格式与 `/v1/chat` 相同。
 
 ---
 
-## 示例
+## `POST /v1/code`
 
-### curl：单轮非流式
+Code 模式对话（与 `min-agent code` 相同的项目感知 prompt 和工具集）。
 
-```bash
-curl -sS http://127.0.0.1:8787/v1/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message":"List files in current directory","model":"gpt-4o-mini"}'
+请求体与 `/v1/chat` 相同，响应额外包含 `mode: "code"` 和 `project` 字段。
+
+```json
+// 请求
+{ "message": "add error handling to the login function", "stream": true }
+
+// 响应（非流式）额外字段
+{ "mode": "code", "project": { "languages": ["TypeScript"], "framework": "Next.js", ... }, ... }
 ```
 
-### curl：SSE 流式
+---
 
-```bash
-curl -sS -N http://127.0.0.1:8787/v1/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message":"Say hi in one sentence","stream":true}'
+## `POST /v1/mcp`
+
+添加 MCP 服务器。
+
+```json
+// 本地 stdio
+{ "name": "filesystem", "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+
+// 远程 HTTP
+{ "name": "remote", "url": "https://mcp.example.com", "token": "xxx" }
 ```
 
-### 带鉴权
+响应：`{ "ok": true, "name": "filesystem" }`
 
-```bash
-export MIN_AGENT_SERVE_TOKEN=secret
-min-agent serve &
-curl -sS http://127.0.0.1:8787/health \
-  -H "Authorization: Bearer secret"
+注意：添加后需重启 serve 进程才能连接新服务器。
+
+---
+
+## `DELETE /v1/mcp/:name`
+
+删除 MCP 服务器配置。
+
+```json
+{ "ok": true, "deleted": "filesystem" }
 ```
 
 ---
 
-## 与 OpenCode / 其他客户端的对比说明
+## 错误码
 
-本 API **不是** OpenAI Chat Completions 的完全兼容实现；字段与事件名为 min-agent 专用。若需对接现有 OpenAI SDK，请在网关层做映射。
+| 状态 | 说明 |
+|------|------|
+| 400 | 请求参数错误 |
+| 401 | 未授权 |
+| 404 | 资源不存在 |
+| 413 | 请求体过大（>2MB） |
+| 415 | Content-Type 不是 JSON |
+| 500 | 内部错误 |
 
 ---
 
-## 版本
+## 示例
+
+```bash
+# 单轮对话
+curl http://127.0.0.1:8787/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"list files"}'
 
-文档与实现随仓库版本迭代；`GET /health` 中的 `version` 来自项目根目录 `package.json`。
+# 流式
+curl -N http://127.0.0.1:8787/v1/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"say hi","stream":true}'
+
+# 添加记忆
+curl -X POST http://127.0.0.1:8787/v1/memory \
+  -H "Content-Type: application/json" \
+  -d '{"content":"prefer TypeScript","tags":["preference"]}'
+
+# 项目扫描
+curl http://127.0.0.1:8787/v1/project
+
+# 压缩会话
+curl -X POST http://127.0.0.1:8787/v1/chat/compact \
+  -H "Content-Type: application/json" \
+  -d '{"session_id":"abc123"}'
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "min-agent",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Minimal AI coding agent with tool use, MCP, and skills support",
   "license": "MIT",