min-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) min-agent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,251 @@
+# min-agent
+
+轻量级 AI Coding Agent，支持工具调用（读写文件、Shell、搜索）、MCP 与 Skill。  
+兼容 OpenAI 风格 API（OpenAI、Ollama、vLLM、MiniMax、DeepSeek 等）。
+
+## 安装
+
+```bash
+npm install -g min-agent
+```
+
+## 快速开始
+
+```bash
+# 1) 交互式配置 provider / api key / 默认模型
+min-agent setup
+
+# 2) 单轮问答
+min-agent chat "hello"
+min-agent chat "read package.json and tell me the version"
+min-agent chat "帮我搜索一下最新的 AI 新闻"
+
+# 3) 进入多轮对话
+min-agent chat
+```
+
+## 首次运行会自动初始化
+
+在当前项目目录自动确保以下结构存在：
+
+- `.min-agent/skills/`
+- `.min-agent/mcp.json`（默认 `{ "mcpServers": {} }`）
+
+用户全局技能目录 `~/.agents/skills/` 不会自动创建；若你自行创建并放入 `SKILL.md`，启动时会被扫描加载（见下文「Skill 安装」）。
+
+## CLI 命令
+
+| Command | Description |
+|---------|-------------|
+| `min-agent setup` | 交互配置 API URL、Key、默认模型 |
+| `min-agent chat <message>` | 单轮消息 |
+| `min-agent chat` | 多轮交互聊天 |
+| `min-agent chat -m <model> <message>` | 指定模型发送消息 |
+| `min-agent models` | 拉取并列出可用模型 |
+| `min-agent mcp add <name> <cmd...>` | 添加本地 MCP（stdio，默认先验证） |
+| `min-agent mcp add <name> --url <url> [--sse] [--token …]` | 添加远程 MCP（HTTP） |
+| `min-agent mcp remove <name>` | 删除 MCP 服务 |
+| `min-agent mcp list` | 列出 MCP 服务 |
+| `min-agent mcp check` | 检查所有 MCP 服务可用性 |
+| `min-agent skills list` | 列出已发现 skills |
+| `min-agent rules` | 查看已加载规则来源 |
+| `min-agent rules edit` | 编辑全局规则文件 |
+| `min-agent history` | 查看会话历史 |
+| `min-agent memory` | 查看记忆 |
+| `min-agent memory add <text>` | 新增记忆 |
+| `min-agent memory search <query>` | 检索记忆 |
+| `min-agent memory delete <index>` | 删除记忆 |
+
+## 交互聊天 Slash 命令（`min-agent chat` 内）
+
+| Slash Command | Description |
+|---------------|-------------|
+| `/clear` | 清空当前会话消息 |
+| `/compact` | 强制压缩上下文 |
+| `/model [name]` | 查看或设置默认模型 |
+| `/models` | 拉取并列出 provider 模型 |
+| `/memory [text]` | 查看记忆或保存记忆 |
+| `/skills` | 列出当前已发现 skills |
+| `/mcp` | 查看 MCP 服务与连接状态 |
+| `/tokens` | 显示上下文 token 估算 |
+| `/help` | 显示帮助 |
+| `/exit` | 退出聊天 |
+
+## 配置文件与加载规则
+
+### Provider 配置
+
+保存在 `~/.min-agent/config.json`：
+
+```json
+{
+  "provider": {
+    "type": "openai-compatible",
+    "baseURL": "https://api.openai.com/v1",
+    "apiKey": "sk-...",
+    "defaultModel": "gpt-4o"
+  }
+}
+```
+
+说明：
+
+- `setup` 时根据填写信息自动拉取模型列表。
+- Ollama 支持填 `http://host:11434` 或 `http://host:11434/v1`，会自动兼容。
+
+### MCP 配置
+
+项目级配置：`.min-agent/mcp.json`
+
+### 规则（Instructions）加载顺序
+
+1. 全局规则：`~/.min-agent/rules.md`
+2. 项目规则（从当前目录向上查找首个命中）：
+   - `./AGENTS.md`
+   - `./RULES.md`
+   - `./CLAUDE.md`
+   - `./.min-agent/AGENTS.md`
+3. `~/.min-agent/config.json` 的 `instructions` 字段中声明的本地文件与远程 URL
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `bash` | 执行 shell 命令 |
+| `read` | 读取文件 |
+| `write` | 写入/创建文件 |
+| `edit` | 文本替换编辑 |
+| `glob` | 按模式查找文件 |
+| `grep` | 按内容搜索 |
+| `web_search` | 联网搜索（SearXNG） |
+| `web_fetch` | 抓取网页内容（含 Firecrawl SPA 兜底） |
+
+## 工具输出与截断
+
+内置工具与 MCP 返回的文本若超过约 **2000 行**或 **50KB（UTF-8）**，会将**全文**保存到 `~/.min-agent/tool-output/tool-*.txt`，并在返回内容中给出**预览 + 文件路径**；请用 `read`（`startLine`/`endLine`）或 `grep` 分段查看。
+
+- **`bash`**：使用流式收集；内存中累计超过 **16MB** 会终止进程并提示改用重定向到文件。预览默认保留**输出尾部**（便于看日志）。
+- **其它文本类工具**（`read`、`grep`、`web_fetch`、`web_search`、`glob`、MCP）：超长时预览默认保留**开头**（`head`），全文仍在上述目录。
+
+该目录下旧文件会按修改时间做简单清理（约保留 7 天）。
+
+## Skill 安装
+
+会在以下目录递归查找 `**/SKILL.md`（**靠后的路径覆盖同名 skill**，即项目内优先于全局）：
+
+1. `~/.agents/skills/`（用户全局，跨项目共享）
+2. `<cwd>/.min-agent/skills/`
+3. `<cwd>/.agent-demo/skills/`
+4. `<cwd>/.opencode/skills/`
+5. `<cwd>/.claude/skills/`
+
+创建目录与文件示例：
+
+```text
+~/.agents/skills/<your-skill>/SKILL.md
+.min-agent/skills/<your-skill>/SKILL.md
+```
+
+`SKILL.md` 最小格式：
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+# Instructions for the agent...
+```
+
+可用命令：
+
+```bash
+min-agent skills list
+```
+
+## MCP 安装
+
+配置在项目目录 `.min-agent/mcp.json`。
+
+### 本地 MCP（stdio）
+
+```bash
+min-agent mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp
+min-agent mcp add memory npx -y @modelcontextprotocol/server-memory
+min-agent mcp add custom --skip-check node ./my-mcp-server.js
+```
+
+### 远程 MCP（HTTP）
+
+通过 `url` 连接远端 MCP，使用 `@modelcontextprotocol/sdk` 的 **Streamable HTTP**；默认 `remoteTransport` 为 `auto`：先尝试 Streamable HTTP，失败再回退 **SSE**（兼容旧版 HTTP+SSE）。
+
+```bash
+min-agent mcp add myremote --url https://api.example.com/mcp
+min-agent mcp add myremote --url https://api.example.com/mcp --token "$YOUR_BEARER_TOKEN"
+min-agent mcp add legacy --url https://old.example.com/sse --sse
+min-agent mcp add legacy --url https://old.example.com/sse --ext/event-stream
+min-agent mcp list
+min-agent mcp check
+```
+
+手写配置示例：
+
+```json
+{
+  "mcpServers": {
+    "remote-demo": {
+      "url": "https://example.com/mcp",
+      "remoteTransport": "auto",
+      "token": "optional-bearer-token",
+      "headers": { "X-Custom-Header": "value" },
+      "enabled": true
+    }
+  }
+}
+```
+
+- `token`：可选；若未设置 `Authorization`，会自动添加 `Bearer <token>`。
+- `remoteTransport`：`auto` | `streamable-http` | `sse`；CLI 中 `--sse` 等价于 `sse`。
+
+说明：
+
+- `mcp add` 默认会先验证连通性；验证失败不会写入配置。
+- 离线或私有场景可使用 `--skip-check` 跳过添加时验证。
+- `mcp check` 会检查配置中所有服务（含远程），若有失败会返回非零退出码。
+
+聊天内可用：
+
+```text
+/mcp
+```
+
+## 常见问题（Troubleshooting）
+
+### 1) `AI_APICallError: Not Found`
+
+常见原因是 provider `baseURL` 不匹配（例如 Ollama 未使用 `/v1` 路径）。  
+建议先执行：
+
+```bash
+min-agent setup
+min-agent models
+```
+
+确认可以正常拉取模型列表。
+
+### 2) `models` 拉取为空
+
+- 检查 `apiKey`、`baseURL` 是否正确
+- 检查网络或服务端是否可达
+- 检查服务是否实现 `/models`（Ollama 已做 `/v1/models` 兼容重试）
+
+### 3) MCP 添加后不可用
+
+- 先 `min-agent mcp list` 看是否已配置
+- 在聊天内 `/mcp` 看连接状态（connected/disconnected/disabled）
+- **本地 stdio**：检查命令是否可执行（如 `npx` 是否可用）
+- **远程 URL**：确认地址为 `http(s)://`，必要时加 `--sse` 强制使用旧版 SSE 传输，或用 `mcp check` 查看具体错误信息
+
+## License
+
+MIT

package/bin/min-agent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts"

package/docs/API.md

@@ -0,0 +1,216 @@
+# min-agent HTTP API
+
+通过 `min-agent serve` 启动本地 HTTP 服务，以编程方式调用与 CLI `chat` 相同的代理能力（同一套 MCP、技能、规则、工具与模型配置）。
+
+## 启动
+
+```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 等确认会自动通过，请勿把未鉴权服务暴露到公网。
+
+---
+
+## 通用约定
+
+- **Base URL**：`http://<host>:<port>`
+- **请求体**：JSON，`Content-Type: application/json`
+- **响应体**：JSON，除非注明为 SSE
+- **工作目录**：与启动 `serve` 时的 `process.cwd()` 一致（影响 `read`/`bash` 等工具路径）
+- **单例初始化**：进程启动时连接 MCP、扫描技能并加载规则；之后请求复用该状态。修改规则文件后可调用下方「重载规则」接口或重启进程
+
+---
+
+## `GET /health`
+
+存活检查。
+
+**响应 200**
+
+```json
+{
+  "ok": true,
+  "service": "min-agent",
+  "version": "0.1.0"
+}
+```
+
+---
+
+## `GET /v1/meta`
+
+运行环境摘要。
+
+**响应 200**
+
+```json
+{
+  "version": "0.1.0",
+  "cwd": "/path/to/project",
+  "instructions_chars": 1234
+}
+```
+
+---
+
+## `GET /v1/models`
+
+从当前配置的 OpenAI 兼容提供商拉取模型列表（与 CLI `min-agent models` 同源）。
+
+**响应 200**
+
+```json
+{
+  "default_model": "gpt-4.1",
+  "models": ["gpt-4.1", "gpt-4o-mini", "..."]
+}
+```
+
+---
+
+## `POST /v1/chat/reload-instructions`
+
+重新从磁盘加载 `AGENTS.md`、规则与 `config.json` 中的 instructions 片段（不重启 MCP）。
+
+**响应 200**
+
+```json
+{
+  "ok": true,
+  "instructions_chars": 1234
+}
+```
+
+---
+
+## `POST /v1/chat`
+
+执行一轮或多轮对话（与 CLI 使用相同的 `streamText` + 工具集）。
+
+### 请求体字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `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` 一起使用，用于构造多模态用户消息 |
+
+### 会话续写 `session_id`
+
+- 请求体必须包含 **`message`**（新用户发言）
+- 服务端加载该会话已有 `messages`，追加新用户消息后调用模型，并在本轮结束后 **写回同一 `session_id`**
+
+### 非流式 `stream: false`（默认）
+
+**响应 200**
+
+```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
+}
+```
+
+- `messages`：已包含本轮助手回复（就地追加，与 CLI 行为一致）
+- `tool_results` 中单条输出过长时会被截断并附带说明后缀
+- 未使用 `session_id` 时 `session_id` 字段为 `undefined`/省略
+
+### 流式 `stream: true`
+
+- **Headers**：`Content-Type: text/event-stream`
+- **Body**：SSE，每条事件为一行 `data: <json>\n\n`
+
+事件 `type` 取值：
+
+| `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 行为对齐）。
+
+### 错误 HTTP 状态
+
+| 状态 | 说明 |
+|------|------|
+| `400` | JSON 无效或缺少 `message`/`messages` |
+| `401` | 配置了 `MIN_AGENT_SERVE_TOKEN` 但未携带合法 Bearer |
+| `404` | `session_id` 不存在 |
+| `413` | 请求体超过约 2MB |
+| `415` | 非 `application/json` |
+| `500` | 未配置提供商等内部错误 |
+
+---
+
+## `OPTIONS *`
+
+当启用 `MIN_AGENT_SERVE_CORS` 时，用于浏览器预检；返回 `204`。
+
+---
+
+## 示例
+
+### curl：单轮非流式
+
+```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"}'
+```
+
+### 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}'
+```
+
+### 带鉴权
+
+```bash
+export MIN_AGENT_SERVE_TOKEN=secret
+min-agent serve &
+curl -sS http://127.0.0.1:8787/health \
+  -H "Authorization: Bearer secret"
+```
+
+---
+
+## 与 OpenCode / 其他客户端的对比说明
+
+本 API **不是** OpenAI Chat Completions 的完全兼容实现；字段与事件名为 min-agent 专用。若需对接现有 OpenAI SDK，请在网关层做映射。
+
+---
+
+## 版本
+
+文档与实现随仓库版本迭代；`GET /health` 中的 `version` 来自项目根目录 `package.json`。

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "min-agent",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Minimal AI coding agent with tool use, MCP, and skills support",
+  "license": "MIT",
+  "bin": {
+    "min-agent": "./bin/min-agent.js"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "tsconfig.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/lemon8510/min-agent.git"
+  },
+  "bugs": {
+    "url": "https://gitee.com/lemon8510/min-agent/issues"
+  },
+  "homepage": "https://gitee.com/lemon8510/min-agent",
+  "scripts": {
+    "dev": "bun run src/cli.ts",
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "coding",
+    "mcp",
+    "llm",
+    "openai-compatible",
+    "coding-agent",
+    "http-api"
+  ],
+  "dependencies": {
+    "@ai-sdk/openai": "3.0.53",
+    "@ai-sdk/provider": "3.0.8",
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "ai": "6.0.168",
+    "glob": "13.0.5"
+  },
+  "devDependencies": {
+    "@types/node": "22.13.9",
+    "tsx": "4.19.4",
+    "typescript": "5.8.2"
+  }
+}