ai-agent-router 0.1.21 → 0.2.1

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/.next/dev/types/validator.js

@@ -63,6 +63,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 {
     const handler = {};
 }
+// Validate ../../../src/app/api/ide/openclaw/apply/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/available-models/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/preview/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/restore/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/save/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/status/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/openclaw/test/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/apply/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/available-models/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/preview/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/restore/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/save/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/status/route.ts
+{
+    const handler = {};
+}
+// Validate ../../../src/app/api/ide/opencode/test/route.ts
+{
+    const handler = {};
+}
 // Validate ../../../src/app/api/logs/route.ts
 {
     const handler = {};

package/dist/.next/types/validator.js

@@ -63,6 +63,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 {
     const handler = {};
 }
+// Validate ../../src/app/api/ide/openclaw/apply/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/available-models/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/preview/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/restore/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/save/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/status/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/openclaw/test/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/apply/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/available-models/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/preview/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/restore/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/save/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/status/route.ts
+{
+    const handler = {};
+}
+// Validate ../../src/app/api/ide/opencode/test/route.ts
+{
+    const handler = {};
+}
 // Validate ../../src/app/api/logs/route.ts
 {
     const handler = {};

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/ide/claude/apply/route.js

@@ -32,27 +32,40 @@ async function POST(request) {
         // 获取当前网关地址和API Key（从数据库读取）
         const gatewayAddress = await getGatewayAddress();
         const gatewayApiKey = await getGatewayApiKey();
-        // 生成配置对象
         const modelMapping = { haiku, sonnet, opus, default: defaultModel, reasoning: reasoningModel };
-        const config = generateClaudeConfig(gatewayAddress, gatewayApiKey, modelMapping);
-        // 备份原有配置
+        const aarEnv = buildAarEnv(gatewayAddress, gatewayApiKey, modelMapping);
         const backupResult = backupOriginalConfig();
         if (!backupResult.success) {
             return server_1.NextResponse.json({ error: backupResult.error }, { status: 500 });
         }
-        // 确保目录存在
         if (!(0, fs_1.existsSync)(CLAUDE_DIR)) {
             (0, fs_1.mkdirSync)(CLAUDE_DIR, { recursive: true });
         }
-        // 验证并写入新配置
-        const validationResult = validateAndWriteConfig(config);
+        let configToWrite;
+        if ((0, fs_1.existsSync)(SETTINGS_FILE)) {
+            try {
+                const existing = JSON.parse((0, fs_1.readFileSync)(SETTINGS_FILE, 'utf-8'));
+                configToWrite = {
+                    ...existing,
+                    env: { ...(existing.env || {}), ...aarEnv },
+                    router_provider: 'aar',
+                };
+            }
+            catch {
+                configToWrite = generateClaudeConfig(gatewayAddress, gatewayApiKey, modelMapping);
+            }
+        }
+        else {
+            configToWrite = generateClaudeConfig(gatewayAddress, gatewayApiKey, modelMapping);
+        }
+        const validationResult = validateAndWriteConfig(configToWrite);
         if (!validationResult.success) {
             return server_1.NextResponse.json({ error: validationResult.error }, { status: 500 });
         }
         return server_1.NextResponse.json({
             success: true,
             message: 'Configuration applied successfully',
-            config,
+            config: configToWrite,
             backup: backupResult.existed ? 'Created backup' : 'No existing config to backup',
             previousWasFromAar: backupResult.existed && backupResult.isFromAar,
         });
@@ -80,50 +93,48 @@ async function getGatewayApiKey() {
     const apiKeyConfig = await (0, queries_1.getConfig)('api_key');
     return apiKeyConfig?.value || 'your-gateway-api-key';
 }
-/**
- * 生成 Claude 配置
- */
+/** 仅生成 AAR 相关的 env 字段，用于合并到现有配置 */
+function buildAarEnv(gatewayAddress, gatewayApiKey, modelMapping) {
+    return {
+        ANTHROPIC_AUTH_TOKEN: gatewayApiKey,
+        ANTHROPIC_BASE_URL: gatewayAddress,
+        ANTHROPIC_DEFAULT_HAIKU_MODEL: modelMapping.haiku,
+        ANTHROPIC_DEFAULT_OPUS_MODEL: modelMapping.opus,
+        ANTHROPIC_DEFAULT_SONNET_MODEL: modelMapping.sonnet,
+        ANTHROPIC_MODEL: modelMapping.default,
+        ANTHROPIC_REASONING_MODEL: modelMapping.reasoning,
+        API_TIMEOUT_MS: '3000000',
+        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1,
+        hasCompletedOnboarding: true,
+    };
+}
+/** 生成完整 Claude 配置（仅在无现有文件时使用） */
 function generateClaudeConfig(gatewayAddress, gatewayApiKey, modelMapping) {
     return {
-        // 路由提供者标识，标识配置来自当前工具 aar
         router_provider: 'aar',
-        env: {
-            ANTHROPIC_AUTH_TOKEN: gatewayApiKey,
-            ANTHROPIC_BASE_URL: gatewayAddress,
-            ANTHROPIC_DEFAULT_HAIKU_MODEL: modelMapping.haiku,
-            ANTHROPIC_DEFAULT_OPUS_MODEL: modelMapping.opus,
-            ANTHROPIC_DEFAULT_SONNET_MODEL: modelMapping.sonnet,
-            ANTHROPIC_MODEL: modelMapping.default,
-            ANTHROPIC_REASONING_MODEL: modelMapping.reasoning,
-            API_TIMEOUT_MS: '3000000',
-            CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: 1,
-            hasCompletedOnboarding: true,
-        },
+        env: buildAarEnv(gatewayAddress, gatewayApiKey, modelMapping),
     };
 }
 /**
  * 备份原有配置
- * 返回原有配置是否来自当前工具（router_provider === 'aar'）
+ * 仅在当前配置不是 AAR 时写入备份，这样「还原」才能恢复到应用 AAR 前的状态
  */
 function backupOriginalConfig() {
     try {
-        // 检查原有配置是否存在
         const existing = (0, fs_1.existsSync)(SETTINGS_FILE);
         if (existing) {
-            // 读取原有配置
             const originalConfig = (0, fs_1.readFileSync)(SETTINGS_FILE, 'utf-8');
-            // 解析配置检查 router_provider
             let isFromAar = false;
             try {
                 const parsedConfig = JSON.parse(originalConfig);
                 isFromAar = parsedConfig.router_provider === 'aar';
             }
-            catch (error) {
-                // 解析失败，不影响备份操作
+            catch {
                 isFromAar = false;
             }
-            // 写入备份文件
-            (0, fs_1.writeFileSync)(BACKUP_FILE, originalConfig, 'utf-8');
+            if (!isFromAar) {
+                (0, fs_1.writeFileSync)(BACKUP_FILE, originalConfig, 'utf-8');
+            }
             return { success: true, existed: true, isFromAar };
         }
         return { success: true, existed: false, isFromAar: false };

package/dist/src/app/api/ide/claude/status/route.js

@@ -45,6 +45,8 @@ async function GET(request) {
                 lastUpdated: undefined,
                 matchCurrentGateway: false,
                 routerProvider: undefined,
+                currentGatewayAddress: gatewayAddress,
+                currentGatewayApiKey: gatewayApiKey,
             });
         }
         // 读取配置文件
@@ -78,7 +80,7 @@ async function GET(request) {
                 }
             }
         }
-        // 提取配置状态
+        // 提取配置状态；返回完整 config 供前端在非 AAR 时展示原有配置文件
         const status = {
             applied: true,
             modelMapping: extractModelMapping(config),
@@ -89,6 +91,9 @@ async function GET(request) {
             matchCurrentGateway,
             routerProvider: config.router_provider,
             tempMapping,
+            config,
+            currentGatewayAddress: gatewayAddress,
+            currentGatewayApiKey: gatewayApiKey,
         };
         return server_1.NextResponse.json(status);
     }