ai-agent-router 0.1.21 → 0.2.0

package/README.md

@@ -1,19 +1,19 @@
 # AI Agent Router
 
-一个统一的 API 网关，用于管理多个 AI 模型供应商（Anthropic、OpenAI、Gemini 等），为 Claude、Zcode、Alma 等客户端软件提供统一的接口。
+一个统一的 API 网关，用于管理多个 AI 模型供应商（Anthropic、OpenAI、Gemini 等），为 Claude、Cursor、Alma 等客户端提供统一接口。
 
 ## 功能特性
 
 - ✅ 支持多种 AI 模型协议（OpenAI、Anthropic、Gemini）
-- ✅ 独立 Gateway 服务架构，可与 Web UI 分离运行
+- ✅ 一键启动：前台 Web UI + 网关服务，默认后台运行
 - ✅ Web 管理界面，可视化配置和管理
 - ✅ 模型供应商管理（添加、编辑、删除）
 - ✅ 模型管理（手动添加、自动拉取模型列表）
 - ✅ 请求日志记录和查看（支持流式响应的美化展示）
 - ✅ 双端点支持（`/v1/*` 和 `/api/gateway/*`）
-- ✅ API Key 认证保护 Gateway 服务
-- ✅ CLI 工具，易于安装和使用
-- ✅ SQLite 数据库，轻量级存储
+- ✅ API Key 认证保护网关服务
+- ✅ CLI 工具（`aar`），支持后台运行与 `aar stop` 停止
+- ✅ SQLite 数据库，数据存储在 `~/.aar/`
 
 ## 安装
 
@@ -21,35 +21,69 @@
 npm install -g ai-agent-router
 ```
 
+安装后可使用命令 `aar` 或 `npx ai-agent-router`。
+
 ## 使用方法
 
-### 启动完整服务（Web UI + Gateway）
+### 启动服务（默认：后台运行 Web UI + 网关）
 
 ```bash
 aar start
 ```
 
-默认在 `http://localhost:9527` 启动 Web 管理界面，Gateway 服务运行在 `http://localhost:1357`。
+- **默认行为**：在后台同时启动 Web 管理界面和网关服务，关闭终端后进程继续运行。
+- 前台 UI：`http://localhost:9527`
+- 网关地址：`http://localhost:1357`（端口可在 Web 界面中配置）
+
+启动后控制台会输出访问地址与网关状态，例如：
+
+```
+-------------------------------------------
+  AI Agent Router
+-------------------------------------------
+  前台 UI:     http://localhost:9527
+  网关地址:   http://localhost:1357
+  网关状态:   运行中
+  运行模式:   后台运行（关闭终端不影响）
+  停止服务:   aar stop
+-------------------------------------------
+```
+
+### 停止后台服务
+
+```bash
+aar stop
+```
+
+会停止由 `aar start` 在后台启动的 Web UI 与网关进程。
+
+### 前台运行（附着当前终端）
 
-### 仅启动 Gateway 服务
+若希望在前台运行、用 Ctrl+C 结束：
 
 ```bash
-aar gateway
+aar start --no-background
 ```
 
-仅启动独立的 API 网关服务，默认在 `http://localhost:1357`。
+### 仅启动 Web UI（不启动网关）
+
+```bash
+aar start --no-gateway
+```
+
+仅启动管理界面，网关可在 Web 界面里再手动启动。
 
 ### 配置选项
 
 ```bash
-# 指定 Web UI 端口
-aar start --port 8080
+# 指定 Web UI 端口（默认 9527）
+aar start -p 8080
 
-# 指定主机名
-aar start --hostname 0.0.0.0
+# 指定网关端口（默认从配置或 1357）
+aar start -g 3000
 
-# 指定 Gateway 端口
-aar gateway --port 3000
+# 组合：前台运行 + 自定义端口
+aar start --no-background -p 9527 -g 1357
 ```
 
 ### 配置管理
@@ -58,93 +92,58 @@ aar gateway --port 3000
 # 获取配置
 aar config --get port
 
-# 设置配置
-aar config --set port 8080
-
-# 设置 Gateway API Key（用于外部客户端认证）
+# 设置配置（key 与 value 用空格分隔）
+aar config --set port 1357
 aar config --set api_key "your-secret-key"
 ```
 
+常用配置项：`port`（网关端口）、`api_key`（网关 API Key，用于客户端认证）。
+
 ## Web 管理界面
 
-启动后访问 `http://localhost:9527`，你可以：
+启动后访问 **http://localhost:9527**，可以：
 
-1. **配置网关**：设置端口、API Key 等
+1. **配置网关**：端口、API Key 等
 2. **管理供应商**：添加、编辑、删除模型供应商
-3. **管理模型**：手动添加模型或一键拉取模型列表
-4. **查看日志**：查看所有 API 请求日志，包括流式响应的美化显示
-5. **服务管理**：独立启动/停止 Gateway 服务，不影响 Web UI
-
-## 添加供应商
-
-1. 访问 Web 界面，进入"供应商"页面
-2. 点击"添加供应商"
-3. 填写信息：
-   - 名称：供应商名称（如 "OpenAI"）
-   - 协议：选择协议类型（OpenAI、Anthropic、Gemini）
-   - Base URL：API 基础 URL（如 `https://api.openai.com/v1`）
-   - API Key：供应商的 API Key
-
-## 添加模型
-
-### 手动添加
+3. **管理模型**：手动添加或一键拉取模型列表
+4. **查看日志**：API 请求日志，含流式响应美化
+5. **服务管理**：在界面内启动/停止网关（使用 `aar start` 时通常已自动启动）
 
-1. 进入"模型"页面
-2. 点击"手动添加"
-3. 选择供应商，填写模型名称和模型 ID
+## 添加供应商与模型
 
-### 自动拉取
+1. 打开 Web 界面 →「供应商」→「添加供应商」
+2. 填写：名称、协议（OpenAI / Anthropic / Gemini）、Base URL、API Key
+3. 在「模型」页可手动添加模型，或使用「拉取模型列表」从供应商拉取
 
-1. 进入"模型"页面
-2. 在"一键拉取模型列表"区域，点击对应供应商的"拉取模型"按钮
-3. 系统会自动从供应商 API 拉取可用模型列表
+## 使用网关 API
 
-## 使用网关
+配置好供应商和模型后，客户端可请求网关（默认 `http://localhost:1357`）。
 
-配置好供应商和模型后，客户端可以通过以下方式使用：
+### OpenAI 兼容
 
-### Gateway 端点（推荐 - 独立服务）
-
-Gateway 服务运行在 `http://localhost:1357`，支持两种兼容的端点：
-
-#### OpenAI 兼容接口
-
-```
+```http
 POST http://localhost:1357/v1/chat/completions
 Content-Type: application/json
-x-api-key: your-gateway-api-key
+Authorization: Bearer your-gateway-api-key
 
 {
   "model": "gpt-4",
   "messages": [...],
-  "stream": true  // 支持流式响应
+  "stream": true
 }
 ```
 
-#### Gateway 专用接口
+### 网关路径形式
 
-```
+```http
 POST http://localhost:1357/api/gateway/v1/chat/completions
-Content-Type: application/json
-x-api-key: your-gateway-api-key
-
-{
-  "model": "gpt-4",
-  "messages": [...],
-  "stream": true  // 支持流式响应
-}
-```
-
-### 模型列表
-
-```
-GET http://localhost:1357/v1/models
-GET http://localhost:1357/api/gateway/models
+GET  http://localhost:1357/v1/models
+GET  http://localhost:1357/api/gateway/models
 ```
 
-### Anthropic 兼容接口
+### Anthropic 兼容
 
-```
+```http
 POST http://localhost:1357/api/gateway/v1/messages
 Content-Type: application/json
 x-api-key: your-gateway-api-key
@@ -155,63 +154,53 @@ x-api-key: your-gateway-api-key
 }
 ```
 
-### 认证说明
-
-- 如果配置了 Gateway API Key，客户端需要在请求头中提供：`x-api-key: your-gateway-api-key`
-- 支持 Bearer token 格式：`Authorization: Bearer your-gateway-api-key`
+认证：若在配置中设置了 API Key，请求头需带 `x-api-key` 或 `Authorization: Bearer <key>`。
 
 ## 开发
 
-### 本地开发
-
 ```bash
 # 安装依赖
 npm install
 
-# 开发模式
+# 开发模式（仅 Next 前台，端口 9527）
 npm run dev
 
 # 构建
 npm run build
 
-# 启动生产模式
+# 生产启动（等同 aar start，需先 build）
 npm start
 ```
 
 ### 项目结构
 
 ```
-aar/
-├── src/
-│   ├── server/              # 网关服务器
-│   │   ├── gateway.ts       # 核心网关逻辑
-│   │   ├── gateway-server.ts # 独立 Gateway 服务器
-│   │   ├── service-manager.ts # 服务管理器
-│   │   ├── providers/       # 协议适配器
-│   │   └── logger.ts       # 请求日志记录
-│   ├── db/                  # 数据库层
-│   │   ├── database.ts       # 数据库连接
-│   │   ├── schema.ts         # SQLite 表结构
-│   │   └── queries.ts        # 数据库查询
-│   ├── app/                 # Next.js 应用
-│   │   ├── api/             # API 路由
-│   │   │   ├── gateway/     # Gateway 代理端点
-│   │   │   └── service/     # 服务管理端点
-│   │   └── (pages)/        # 前端页面
-│   └── cli/                 # CLI 入口
-│       ├── index.ts         # 主 CLI 程序
-│       └── gateway-server.ts # Gateway CLI 入口
-├── package.json
-└── README.md
+src/
+├── server/                 # 网关与后端
+│   ├── gateway.ts          # 网关请求处理
+│   ├── gateway-server.ts   # 独立网关 HTTP 服务
+│   ├── service-manager.ts  # 进程/服务管理
+│   ├── providers/          # 各协议适配
+│   └── logger.ts           # 请求日志
+├── db/                     # SQLite（~/.aar/gateway.db）
+│   ├── database.ts
+│   ├── schema.ts
+│   └── queries.ts
+├── app/                    # Next.js App Router
+│   ├── api/                # API 路由（gateway、config、service 等）
+│   └── (页面组件)
+└── cli/                    # CLI
+    ├── index.ts            # aar start / stop / config
+    └── gateway-server.ts   # 独立网关进程入口
 ```
 
 ## 技术栈
 
-- **Next.js 14** - 全栈框架
+- **Next.js** - 全栈与 Web UI
 - **TypeScript** - 类型安全
-- **Tailwind CSS** - 样式框架
-- **SQLite3** - 数据库
-- **Commander.js** - CLI 框架
+- **Tailwind CSS** - 样式
+- **SQLite (sql.js)** - 本地存储
+- **Commander.js** - CLI
 
 ## 许可证
 
@@ -219,4 +208,4 @@ MIT
 
 ## 贡献
 
-欢迎提交 Issue 和 Pull Request！
+欢迎提交 Issue 与 Pull Request。

package/dist/src/app/api/gateway/[...path]/route.js

@@ -33,7 +33,7 @@ async function DELETE(request, { params }) {
 }
 async function handleRequest(request, params, method) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const path = params.path.join('/');
         const searchParams = request.nextUrl.searchParams;
         // Get model ID from query

package/dist/src/app/api/gateway/route.js

@@ -17,7 +17,7 @@ async function GET(request) {
 }
 async function handleGatewayRequestDirect(request, method) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const searchParams = request.nextUrl.searchParams;
         let modelId = searchParams.get('model') || searchParams.get('model_id');
         const providerName = searchParams.get('provider');

package/dist/src/app/api/logs/route.js

@@ -35,7 +35,7 @@ function cleanLogData(log) {
 }
 async function GET(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const id = searchParams.get('id');
         const limit = parseInt(searchParams.get('limit') || '100');
@@ -66,7 +66,7 @@ async function GET(request) {
 }
 async function DELETE(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const ids = searchParams.get('ids');
         const clearAll = searchParams.get('clear_all') === 'true';

package/dist/src/app/api/models/route.js

@@ -14,7 +14,7 @@ const providers_1 = require("@/server/providers");
 exports.runtime = 'nodejs';
 async function GET(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const providerId = searchParams.get('provider_id');
         const enabledOnly = searchParams.get('enabled');
@@ -43,7 +43,7 @@ async function GET(request) {
 }
 async function POST(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { provider_id, name, model_id, enabled } = body;
         if (!provider_id || !name || !model_id) {
@@ -64,7 +64,7 @@ async function POST(request) {
 }
 async function PUT(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { id, name, model_id, enabled, provider_id } = body;
         if (!id) {
@@ -92,7 +92,7 @@ async function PUT(request) {
 }
 async function DELETE(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const id = searchParams.get('id');
         if (!id) {
@@ -112,7 +112,7 @@ async function DELETE(request) {
 // Fetch models from provider
 async function PATCH(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { provider_id } = body;
         if (!provider_id) {

package/dist/src/app/api/providers/route.js

@@ -13,7 +13,7 @@ const crypto_1 = require("@/server/crypto");
 exports.runtime = 'nodejs';
 async function GET(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const id = searchParams.get('id');
         const includeKey = searchParams.get('includeKey') === 'true';
@@ -45,7 +45,7 @@ async function GET(request) {
 }
 async function POST(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { name, protocol, base_url, api_key } = body;
         if (!name || !protocol || !base_url || !api_key) {
@@ -70,7 +70,7 @@ async function POST(request) {
 }
 async function PUT(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { id, name, protocol, base_url, api_key } = body;
         if (!id) {
@@ -106,7 +106,7 @@ async function PUT(request) {
 }
 async function DELETE(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const { searchParams } = new URL(request.url);
         const id = searchParams.get('id');
         if (!id) {

package/dist/src/app/api/providers/test/route.js

@@ -10,7 +10,7 @@ const providers_1 = require("@/server/providers");
 exports.runtime = 'nodejs';
 async function POST(request) {
     try {
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json();
         const { provider_id, model_id } = body;
         if (!provider_id || !model_id) {

package/dist/src/app/api/service/start/route.js

@@ -15,7 +15,7 @@ exports.runtime = 'nodejs';
 async function POST(request) {
     try {
         // Initialize database
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const body = await request.json().catch(() => ({}));
         const port = body.port ? parseInt(body.port, 10) : null;
         // Get port from config if not provided

package/dist/src/app/api/service/status/route.js

@@ -10,7 +10,7 @@ exports.runtime = 'nodejs';
 async function GET(request) {
     try {
         // Initialize database
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const status = await service_manager_1.serviceManager.getStatus();
         return server_1.NextResponse.json(status);
     }

package/dist/src/app/api/service/stop/route.js

@@ -10,7 +10,7 @@ exports.runtime = 'nodejs';
 async function POST(request) {
     try {
         // Initialize database
-        (0, database_1.getDatabase)();
+        await (0, database_1.getDatabase)();
         const result = await service_manager_1.serviceManager.stop();
         if (result.error) {
             return server_1.NextResponse.json(result, { status: 400 });

package/dist/src/app/logs/page.js

@@ -10,6 +10,18 @@ const react_1 = require("react");
 const Nav_1 = __importDefault(require("../components/Nav"));
 const ToastProvider_1 = require("../components/ToastProvider");
 const ConfirmDialog_1 = __importDefault(require("../components/ConfirmDialog"));
+/** 将服务端返回的 created_at 格式化为本地显示。无时区后缀时按 UTC 解析再转本地，避免差 8 小时。 */
+function formatCreatedAt(createdAt) {
+    if (!createdAt || typeof createdAt !== 'string')
+        return '';
+    const s = createdAt.trim();
+    if (!s)
+        return '';
+    const hasTz = /[Z+-]\d{2}:?\d{2}$/.test(s);
+    const iso = hasTz ? s : s.replace(' ', 'T') + 'Z';
+    const date = new Date(iso);
+    return Number.isNaN(date.getTime()) ? s : date.toLocaleString('zh-CN');
+}
 function LogsPage() {
     const [logs, setLogs] = (0, react_1.useState)([]);
     const [selectedLog, setSelectedLog] = (0, react_1.useState)(null);
@@ -244,7 +256,7 @@ function LogsPage() {
                                                             }, className: "mt-2 text-xs text-emerald-600 hover:text-emerald-700", children: "\u6E05\u9664\u641C\u7D22" }))] }) }) })) : (logs.map((log) => {
                                             const parsedModel = parseModelFromRequest(log.request_query, log.request_body);
                                             const displayModel = parsedModel || log.model_name || 'Gateway';
-                                            return ((0, jsx_runtime_1.jsxs)("tr", { className: "hover:bg-emerald-50/20 transition-colors duration-300", children: [(0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3", children: (0, jsx_runtime_1.jsx)("input", { type: "checkbox", checked: selectedIds.includes(log.id), onChange: (e) => handleSelectLog(log.id, e.target.checked), className: "w-4 h-4 rounded border-slate-300 text-emerald-600 focus:ring-emerald-500", onClick: (e) => e.stopPropagation() }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsx)("div", { className: "text-xs text-slate-600", children: new Date(log.created_at + 'Z').toLocaleString('zh-CN') }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsxs)("div", { className: "text-xs", children: [(0, jsx_runtime_1.jsx)("div", { className: "font-medium text-slate-800", children: displayModel }), log.provider_name && ((0, jsx_runtime_1.jsx)("div", { className: "text-[10px] text-slate-500", children: log.provider_name }))] }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsx)("span", { className: `px-2 py-0.5 inline-flex text-xs leading-4 font-semibold rounded-lg border ${log.request_method === 'GET' ? 'bg-sky-50 text-sky-700 border-sky-200/50' :
+                                            return ((0, jsx_runtime_1.jsxs)("tr", { className: "hover:bg-emerald-50/20 transition-colors duration-300", children: [(0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3", children: (0, jsx_runtime_1.jsx)("input", { type: "checkbox", checked: selectedIds.includes(log.id), onChange: (e) => handleSelectLog(log.id, e.target.checked), className: "w-4 h-4 rounded border-slate-300 text-emerald-600 focus:ring-emerald-500", onClick: (e) => e.stopPropagation() }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsx)("div", { className: "text-xs text-slate-600", children: formatCreatedAt(log.created_at) }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsxs)("div", { className: "text-xs", children: [(0, jsx_runtime_1.jsx)("div", { className: "font-medium text-slate-800", children: displayModel }), log.provider_name && ((0, jsx_runtime_1.jsx)("div", { className: "text-[10px] text-slate-500", children: log.provider_name }))] }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsx)("span", { className: `px-2 py-0.5 inline-flex text-xs leading-4 font-semibold rounded-lg border ${log.request_method === 'GET' ? 'bg-sky-50 text-sky-700 border-sky-200/50' :
                                                                 log.request_method === 'POST' ? 'bg-emerald-50 text-emerald-700 border-emerald-200/50' :
                                                                     'bg-slate-50 text-slate-600 border-slate-200/50'}`, children: log.request_method }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3", children: (0, jsx_runtime_1.jsx)("div", { className: "text-xs text-slate-600 font-mono max-w-xs truncate", children: log.request_path }) }), (0, jsx_runtime_1.jsx)("td", { className: "px-4 py-3 whitespace-nowrap", children: (0, jsx_runtime_1.jsx)("span", { className: `px-2 py-0.5 inline-flex text-xs leading-4 font-semibold rounded-full border ${log.response_status >= 200 && log.response_status < 300 ? 'bg-emerald-100/80 text-emerald-700 border-emerald-200/50' :
                                                                 log.response_status >= 400 && log.response_status < 500 ? 'bg-amber-100/80 text-amber-700 border-amber-200/50' :