ai-agent-router 0.1.0

package/openspec/changes/improve-gateway-startup/design.md

@@ -0,0 +1,137 @@
+# 设计文档：完善网关代理服务启动逻辑
+
+## Context
+当前网关服务通过 CLI 工具启动（`ai-agent-router start`），Web UI 中的启动/停止按钮只是改变前端本地状态，没有实际控制服务。用户需要能够通过 Web 界面真正启动和停止服务，并且服务状态需要持久化。
+
+## Goals / Non-Goals
+
+### Goals
+- 通过 Web UI 启动/停止网关服务
+- 服务状态持久化，刷新页面后仍能正确显示
+- 服务在后台持续运行，不依赖前端会话
+- 支持服务状态实时同步
+
+### Non-Goals
+- 不支持通过 Web UI 启动多个服务实例（单实例运行）
+- 不实现服务自动重启功能（本次不涉及）
+- 不实现服务监控和告警（后续可扩展）
+
+## Decisions
+
+### Decision 1: 服务启动方式
+**选择**: 通过 Node.js `child_process.spawn` 启动 CLI 命令作为子进程
+
+**理由**:
+- 复用现有的 CLI 启动逻辑，避免重复代码
+- 子进程独立运行，不阻塞主进程
+- 可以监听进程退出事件，自动更新状态
+
+**替代方案考虑**:
+- 直接在主进程中启动服务：会导致 Next.js 开发模式下的热重载问题
+- 使用 PM2 等进程管理器：增加外部依赖，复杂度较高
+
+### Decision 2: 服务状态存储
+**选择**: 使用 SQLite 数据库存储服务状态（status, port, pid, started_at）
+
+**理由**:
+- 项目已使用 SQLite，无需引入新依赖
+- 状态持久化，支持跨会话查询
+- 可以记录服务启动历史
+
+**替代方案考虑**:
+- 仅使用内存存储：刷新页面后状态丢失
+- 使用文件存储：需要处理文件锁和并发问题
+
+### Decision 3: 状态同步机制
+**选择**: 前端定期轮询 `/api/service/status` API（每 2-3 秒）
+
+**理由**:
+- 实现简单，无需 WebSocket 等复杂机制
+- 对于服务状态这种低频变化足够
+- 兼容性好，无需额外配置
+
+**替代方案考虑**:
+- WebSocket 实时推送：增加复杂度，当前场景不需要
+- Server-Sent Events (SSE)：需要额外的连接管理
+
+### Decision 4: 单实例防护
+**选择**: 在启动前检查数据库中是否有运行中的服务记录，并验证进程是否真实存在
+
+**理由**:
+- 防止重复启动导致端口冲突
+- 处理异常退出后数据库状态不一致的情况
+
+**实现**:
+1. 启动前查询数据库中的服务状态
+2. 如果状态为运行中，检查进程是否真实存在（通过 pid）
+3. 如果进程不存在，清理数据库状态，允许启动
+4. 如果进程存在，拒绝启动并返回错误
+
+### Decision 5: 进程管理
+**选择**: 使用 Node.js 原生 `child_process` 模块，记录子进程 PID
+
+**理由**:
+- 无需外部依赖
+- 可以精确控制进程生命周期
+- 可以监听进程退出事件
+
+**实现细节**:
+- 使用 `spawn` 而非 `exec`，避免 shell 注入风险
+- 分离 stdout/stderr，便于日志记录
+- 监听 `exit` 事件，自动更新数据库状态
+
+## Risks / Trade-offs
+
+### Risk 1: 进程异常退出后状态不一致
+**风险**: 如果服务进程异常退出（崩溃、被 kill），数据库状态可能仍显示为运行中
+
+**缓解措施**:
+- 启动前检查进程是否存在
+- 定期健康检查（可选，本次不实现）
+- 监听进程退出事件，自动更新状态
+
+### Risk 2: 端口冲突
+**风险**: 如果配置的端口已被其他进程占用，启动会失败
+
+**缓解措施**:
+- 启动前检测端口是否可用
+- 返回清晰的错误信息
+- 提示用户修改端口配置
+
+### Risk 3: 并发启动请求
+**风险**: 用户快速点击启动按钮，可能触发多个启动请求
+
+**缓解措施**:
+- 在服务管理器中添加启动锁（flag）
+- 启动过程中禁用启动按钮
+- 返回适当的错误信息
+
+### Trade-off: 状态同步延迟
+**权衡**: 轮询方式有 2-3 秒延迟，但实现简单
+
+**接受**: 对于服务启动/停止这种低频操作，2-3 秒延迟可接受
+
+## Migration Plan
+
+### 步骤
+1. 添加数据库 schema 和查询方法（向后兼容，不影响现有功能）
+2. 实现服务管理器（独立模块，不影响现有代码）
+3. 添加服务管理 API（新路由，不影响现有 API）
+4. 修改 Web UI（仅修改启动/停止逻辑，其他功能不变）
+5. 测试验证
+
+### 回滚
+- 如果出现问题，可以回退 Web UI 代码，恢复为仅改变本地状态
+- 数据库 schema 可以保留，不影响其他功能
+- 服务管理 API 可以禁用，不影响网关核心功能
+
+## Open Questions
+
+1. **服务日志输出**: 是否需要将服务进程的 stdout/stderr 输出到某个地方？当前 CLI 直接输出到控制台。
+   - **决定**: 本次不实现日志收集，后续可扩展
+
+2. **服务配置变更**: 如果用户在服务运行中修改了端口配置，是否需要自动重启服务？
+   - **决定**: 本次不实现自动重启，用户需要手动停止后重新启动
+
+3. **服务健康检查**: 是否需要定期检查服务是否健康（不仅仅是进程存在）？
+   - **决定**: 本次不实现，仅检查进程是否存在

package/openspec/changes/improve-gateway-startup/proposal.md

@@ -0,0 +1,33 @@
+# Change: 完善网关代理服务启动逻辑
+
+## Why
+当前 Web UI 中的启动/停止按钮只是改变前端本地状态，并没有实际启动或停止后台服务。用户点击启动后，如果刷新页面，状态会丢失，服务实际上并没有运行。这导致用户体验不佳，无法通过 Web 界面真正管理网关服务的生命周期。
+
+需要实现真正的服务启动/停止功能，使得：
+1. 点击启动按钮时，实际启动后台网关服务进程
+2. 服务状态持久化，刷新页面后仍能正确显示服务状态
+3. 服务在后台持续运行，不依赖于前端页面会话
+
+## What Changes
+- **新增服务进程管理 API**：提供启动、停止、查询服务状态的 API 端点
+- **新增服务状态持久化**：将服务运行状态存储到数据库，支持跨会话查询
+- **修改 Web UI 启动/停止逻辑**：从仅改变前端状态改为调用后端 API 实际控制服务
+- **新增服务状态同步机制**：前端定期轮询或使用 WebSocket 同步服务状态
+- **新增进程管理功能**：在 Node.js 中启动和管理子进程，确保服务在后台运行
+
+## Impact
+- Affected specs: 
+  - `web-ui` (修改启动/停止功能，新增状态管理)
+  - `api-gateway` (新增服务进程管理能力)
+- Affected code: 
+  - `src/app/page.tsx` - 修改启动/停止按钮逻辑
+  - `src/app/api/gateway/route.ts` - 可能需要调整（如果涉及服务启动）
+  - 新增 `src/app/api/service/route.ts` - 服务管理 API
+  - 新增 `src/server/service-manager.ts` - 服务进程管理逻辑
+  - `src/db/schema.ts` - 可能需要添加服务状态表
+  - `src/db/queries.ts` - 添加服务状态查询/更新方法
+- 技术考虑：
+  - 需要处理进程启动、停止、状态监控
+  - 需要考虑端口冲突检测
+  - 需要考虑服务异常退出时的处理
+  - 需要考虑多实例启动的防护

package/openspec/changes/improve-gateway-startup/specs/api-gateway/spec.md

@@ -0,0 +1,94 @@
+## MODIFIED Requirements
+
+### Requirement: API 网关核心功能
+The system SHALL provide an API gateway that routes requests from clients (Claude, Zcode, Alma) to appropriate AI model providers based on model configuration.
+
+#### Scenario: 启动网关服务
+- **WHEN** 用户执行 `api-gateway start` 命令
+- **THEN** 网关服务器启动并监听配置的端口
+- **AND** Web 管理界面同时启动
+- **WHEN** 用户通过 Web UI 点击启动按钮
+- **THEN** 系统启动网关服务进程（通过 CLI 命令）
+- **AND** 服务在后台运行，不依赖前端会话
+- **AND** 服务状态保存到数据库
+- **AND** 服务持续运行直到用户点击停止或进程异常退出
+
+#### Scenario: 接收客户端请求
+- **WHEN** 客户端（Claude/Zcode/Alma）向网关发送 API 请求
+- **THEN** 网关接收请求并解析模型标识符
+- **AND** 根据模型配置路由到对应的供应商 API
+
+#### Scenario: 转发请求到供应商
+- **WHEN** 网关确定目标供应商和模型
+- **THEN** 使用对应的协议适配器转发请求
+- **AND** 将供应商的响应返回给客户端
+
+#### Scenario: 处理请求错误
+- **WHEN** 供应商 API 返回错误或超时
+- **THEN** 网关返回适当的错误响应给客户端
+- **AND** 错误信息记录到日志中
+
+## ADDED Requirements
+
+### Requirement: 服务进程管理
+The system SHALL provide service management capabilities to start, stop, and query the status of the gateway service through the Web UI.
+
+#### Scenario: 启动服务
+- **WHEN** 用户通过 Web UI 点击启动按钮
+- **THEN** 系统检查服务是否已在运行
+- **AND** 如果未运行，启动服务进程
+- **AND** 如果端口已被占用，返回错误信息
+- **AND** 服务状态保存到数据库
+- **AND** 返回启动结果给前端
+
+#### Scenario: 停止服务
+- **WHEN** 用户通过 Web UI 点击停止按钮
+- **THEN** 系统查找运行中的服务进程
+- **AND** 终止服务进程
+- **AND** 更新数据库状态为已停止
+- **AND** 返回停止结果给前端
+
+#### Scenario: 查询服务状态
+- **WHEN** 前端请求服务状态
+- **THEN** 系统查询数据库中的服务状态
+- **AND** 验证进程是否真实存在（通过 PID）
+- **AND** 如果进程不存在但状态为运行中，更新状态为已停止
+- **AND** 返回当前服务状态（运行中/已停止、端口、启动时间等）
+
+#### Scenario: 服务状态持久化
+- **WHEN** 服务启动成功
+- **THEN** 服务状态（运行中、端口、PID、启动时间）保存到数据库
+- **WHEN** 服务停止
+- **THEN** 数据库状态更新为已停止
+- **WHEN** 用户刷新页面
+- **THEN** 系统从数据库查询服务状态并正确显示
+
+#### Scenario: 单实例防护
+- **WHEN** 用户尝试启动服务
+- **THEN** 系统检查是否已有服务在运行
+- **AND** 如果已有服务运行，拒绝启动并返回错误
+- **AND** 如果数据库状态为运行中但进程不存在，清理状态并允许启动
+
+#### Scenario: 进程异常退出处理
+- **WHEN** 服务进程异常退出（崩溃、被 kill）
+- **THEN** 系统检测到进程退出事件
+- **AND** 自动更新数据库状态为已停止
+- **AND** 前端能够通过状态查询检测到变化
+
+### Requirement: 协议支持
+The system SHALL support multiple AI model protocols including Anthropic, OpenAI, and Gemini.
+
+#### Scenario: OpenAI 协议请求
+- **WHEN** 客户端请求使用 OpenAI 模型
+- **THEN** 网关使用 OpenAI 协议适配器转发请求
+- **AND** 请求格式符合 OpenAI API 规范
+
+#### Scenario: Anthropic 协议请求
+- **WHEN** 客户端请求使用 Anthropic 模型
+- **THEN** 网关使用 Anthropic 协议适配器转发请求
+- **AND** 请求格式符合 Anthropic API 规范
+
+#### Scenario: Gemini 协议请求
+- **WHEN** 客户端请求使用 Gemini 模型
+- **THEN** 网关使用 Gemini 协议适配器转发请求
+- **AND** 请求格式符合 Gemini API 规范

package/openspec/changes/improve-gateway-startup/specs/web-ui/spec.md

@@ -0,0 +1,67 @@
+## MODIFIED Requirements
+
+### Requirement: Web 管理界面
+The system SHALL provide a web-based management interface built with Next.js and Tailwind CSS.
+
+#### Scenario: 访问管理界面
+- **WHEN** 网关服务启动
+- **THEN** Web 管理界面可通过浏览器访问（默认端口或配置的端口）
+- **AND** 界面使用 Tailwind CSS 样式，美观现代
+
+#### Scenario: 网关配置界面
+- **WHEN** 用户访问主页面
+- **THEN** 显示网关配置选项（端口、API_KEY）
+- **AND** 可以修改配置并保存
+- **AND** 配置保存后立即生效或提示重启
+
+#### Scenario: 启动/停止网关
+- **WHEN** 用户点击启动按钮
+- **THEN** 系统调用后端 API 启动网关服务进程
+- **AND** 服务在后台启动并持续运行
+- **AND** 按钮状态变为"运行中"
+- **AND** 显示网关运行状态和端口信息
+- **AND** 服务状态持久化到数据库
+- **WHEN** 用户刷新页面
+- **THEN** 系统从数据库查询服务状态并正确显示
+- **AND** 如果服务正在运行，状态显示为"运行中"
+- **WHEN** 用户点击停止按钮
+- **THEN** 系统调用后端 API 停止网关服务进程
+- **AND** 服务进程被终止
+- **AND** 按钮状态变为"已停止"
+- **AND** 数据库状态更新为已停止
+
+#### Scenario: 服务状态同步
+- **WHEN** 服务在前台运行（通过 CLI 启动）
+- **THEN** Web UI 能够检测到服务状态并正确显示
+- **WHEN** 服务异常退出（崩溃或被 kill）
+- **THEN** Web UI 能够检测到状态变化并更新显示
+- **WHEN** 用户打开多个浏览器标签页
+- **THEN** 所有标签页都能正确显示服务状态
+
+#### Scenario: 供应商管理页面
+- **WHEN** 用户访问供应商管理页面
+- **THEN** 显示供应商列表
+- **AND** 可以添加、编辑、删除供应商
+- **AND** 界面响应式设计，支持移动端
+
+#### Scenario: 模型管理页面
+- **WHEN** 用户访问模型管理页面
+- **THEN** 显示模型列表（按供应商分组）
+- **AND** 可以手动添加模型
+- **AND** 可以点击按钮拉取模型列表
+- **AND** 可以启用/禁用、删除模型
+
+#### Scenario: UI 优化
+- **WHEN** 界面渲染
+- **THEN** 使用 ui-ux-pro-max 进行 UI 优化
+- **AND** 界面美观、易用、符合现代设计规范
+- **AND** 交互流畅，反馈及时
+
+### Requirement: 响应式设计
+The system SHALL provide responsive web interface that works on different screen sizes.
+
+#### Scenario: 移动端访问
+- **WHEN** 用户在移动设备上访问管理界面
+- **THEN** 界面自适应屏幕大小
+- **AND** 所有功能可用
+- **AND** 布局合理，易于操作

package/openspec/changes/improve-gateway-startup/tasks.md

@@ -0,0 +1,47 @@
+## 1. 数据库层
+- [x] 1.1 设计服务状态表 schema（service_status: id, status, port, pid, started_at, updated_at）
+- [x] 1.2 实现服务状态查询方法（getServiceStatus）
+- [x] 1.3 实现服务状态更新方法（updateServiceStatus, setServiceStatus）
+- [x] 1.4 实现服务状态清理方法（清理已停止的进程记录）
+
+## 2. 服务进程管理
+- [x] 2.1 实现服务管理器（ServiceManager 类）
+- [x] 2.2 实现启动服务方法（spawn 子进程运行 CLI start 命令）
+- [x] 2.3 实现停止服务方法（kill 进程，更新状态）
+- [x] 2.4 实现查询服务状态方法（检查进程是否存在，同步数据库状态）
+- [x] 2.5 实现端口冲突检测（启动前检查端口是否被占用）
+- [x] 2.6 实现进程异常退出监听（监听子进程退出事件，更新状态）
+- [x] 2.7 实现单实例防护（防止同时启动多个服务实例）
+
+## 3. 服务管理 API
+- [x] 3.1 创建 `/api/service` 路由
+- [x] 3.2 实现 GET `/api/service/status` - 查询服务状态
+- [x] 3.3 实现 POST `/api/service/start` - 启动服务
+- [x] 3.4 实现 POST `/api/service/stop` - 停止服务
+- [x] 3.5 实现错误处理和状态码返回
+- [x] 3.6 实现请求参数验证（端口、配置等）
+
+## 4. Web UI 修改
+- [x] 4.1 修改启动按钮逻辑，调用 `/api/service/start` API
+- [x] 4.2 修改停止按钮逻辑，调用 `/api/service/stop` API
+- [x] 4.3 实现服务状态轮询（定期调用 `/api/service/status` 同步状态）
+- [x] 4.4 修改状态显示逻辑，从 API 获取真实状态而非本地状态
+- [x] 4.5 添加加载状态和错误提示（启动中、启动失败等）
+- [x] 4.6 实现启动/停止按钮的禁用逻辑（服务运行中禁用启动，已停止禁用停止）
+
+## 5. 错误处理和边界情况
+- [x] 5.1 处理端口已被占用的情况
+- [x] 5.2 处理服务启动失败的情况
+- [x] 5.3 处理服务异常退出的情况（自动更新状态）
+- [x] 5.4 处理页面刷新时的状态恢复
+- [x] 5.5 处理并发启动请求（防止重复启动）
+- [x] 5.6 实现优雅关闭（停止时清理资源）
+
+## 6. 测试和验证
+- [ ] 6.1 测试启动服务功能
+- [ ] 6.2 测试停止服务功能
+- [ ] 6.3 测试状态查询功能
+- [ ] 6.4 测试页面刷新后状态恢复
+- [ ] 6.5 测试端口冲突处理
+- [ ] 6.6 测试服务异常退出处理
+- [ ] 6.7 测试并发启动防护

package/openspec/changes/init-api-gateway/design.md

@@ -0,0 +1,185 @@
+# Design: API 网关架构设计
+
+## Context
+需要构建一个类似 NewAPI 的 API 网关，支持多种 AI 模型协议，提供统一的管理界面和请求日志功能。项目将作为 npm CLI 工具发布，需要支持本地部署和配置。
+
+## Goals / Non-Goals
+
+### Goals
+- 支持多种 AI 模型协议（Anthropic、OpenAI、Gemini）
+- 提供 Web 界面进行配置和管理
+- 记录所有请求日志并提供可视化查看
+- 支持动态添加模型供应商和模型
+- 打包为 CLI 工具，易于安装和使用
+- 使用 SQLite3 作为轻量级数据存储
+
+### Non-Goals
+- 不支持多租户或用户认证（单用户本地使用）
+- 不支持分布式部署（单机运行）
+- 不支持请求限流和配额管理（后续可扩展）
+- 不支持请求缓存（后续可扩展）
+
+## Decisions
+
+### Decision: 使用 Next.js 作为全栈框架
+**Rationale**: 
+- Next.js 提供前后端一体化开发，简化项目结构
+- 内置 API Routes 可以处理网关请求转发
+- 支持 SSR/SSG，便于构建管理界面
+- 生态成熟，易于集成 Tailwind CSS
+
+**Alternatives considered**:
+- Express + React: 需要分别管理前后端，增加复杂度
+- Fastify + Vue: 团队对 Next.js 更熟悉
+
+### Decision: 使用 SQLite3 作为数据库
+**Rationale**:
+- 轻量级，无需额外数据库服务
+- 适合单机部署场景
+- 文件存储，便于备份和迁移
+- Node.js 有成熟的 SQLite3 驱动
+
+**Alternatives considered**:
+- PostgreSQL: 对于单机场景过于重量级
+- JSON 文件: 并发写入和查询性能较差
+
+### Decision: 网关架构采用代理转发模式
+**Rationale**:
+- 简单直接，易于实现和维护
+- 支持协议转换和请求适配
+- 可以统一添加日志、错误处理等横切关注点
+
+**Implementation**:
+- 网关监听配置的端口
+- 接收客户端请求（Claude、Zcode、Alma）
+- 根据模型配置路由到对应的供应商 API
+- 转发请求并返回响应
+
+### Decision: CLI 工具使用 Commander.js
+**Rationale**:
+- 成熟的 Node.js CLI 框架
+- 支持子命令、参数解析、帮助信息
+- 易于集成到 npm 包
+
+**Commands**:
+- `api-gateway start` - 启动网关服务
+- `api-gateway config` - 配置管理（可选）
+
+### Decision: 使用 ui-ux-pro-max 优化 UI
+**Rationale**:
+- 项目已有 ui-ux-pro-max 技能，可以用于生成优化的 UI 设计
+- 确保界面美观和用户体验良好
+
+## Architecture
+
+### 项目结构
+```
+api-gateway/
+├── src/
+│   ├── server/          # 网关服务器
+│   │   ├── gateway.ts   # 核心网关逻辑
+│   │   ├── providers/   # 协议适配器
+│   │   │   ├── anthropic.ts
+│   │   │   ├── openai.ts
+│   │   │   └── gemini.ts
+│   │   └── logger.ts    # 请求日志记录
+│   ├── db/              # 数据库层
+│   │   ├── schema.ts    # SQLite 表结构
+│   │   └── queries.ts   # 数据库查询
+│   ├── app/             # Next.js 应用
+│   │   ├── api/         # API 路由
+│   │   │   ├── providers/  # 供应商管理 API
+│   │   │   ├── models/     # 模型管理 API
+│   │   │   ├── config/     # 配置管理 API
+│   │   │   └── logs/       # 日志查询 API
+│   │   └── (pages)/     # 前端页面
+│   │       ├── page.tsx    # 主页面（配置）
+│   │       └── logs/       # 日志查看页面
+│   └── cli/             # CLI 入口
+│       └── index.ts
+├── package.json
+├── tsconfig.json
+└── tailwind.config.js
+```
+
+### 数据模型
+
+#### providers 表
+- id: INTEGER PRIMARY KEY
+- name: TEXT (供应商名称，如 "OpenAI")
+- protocol: TEXT (协议类型: "openai", "anthropic", "gemini")
+- base_url: TEXT (API 基础 URL)
+- api_key: TEXT (加密存储)
+- created_at: DATETIME
+- updated_at: DATETIME
+
+#### models 表
+- id: INTEGER PRIMARY KEY
+- provider_id: INTEGER (外键到 providers)
+- name: TEXT (模型名称，如 "gpt-4")
+- model_id: TEXT (供应商的模型标识符)
+- enabled: BOOLEAN (是否启用)
+- created_at: DATETIME
+- updated_at: DATETIME
+
+#### request_logs 表
+- id: INTEGER PRIMARY KEY
+- model_id: INTEGER (外键到 models)
+- request_method: TEXT (HTTP 方法)
+- request_path: TEXT (请求路径)
+- request_headers: TEXT (JSON 字符串)
+- request_query: TEXT (JSON 字符串)
+- request_body: TEXT (JSON 字符串)
+- response_status: INTEGER (HTTP 状态码)
+- response_body: TEXT (JSON 字符串)
+- response_time_ms: INTEGER (响应时间)
+- created_at: DATETIME
+
+#### config 表
+- key: TEXT PRIMARY KEY
+- value: TEXT (JSON 字符串)
+- updated_at: DATETIME
+
+### 协议适配
+
+每个协议需要实现统一的适配器接口：
+```typescript
+interface ProviderAdapter {
+  forwardRequest(model: Model, request: GatewayRequest): Promise<GatewayResponse>
+  listModels(provider: Provider): Promise<Model[]>
+}
+```
+
+### 安全考虑
+- API Key 加密存储（使用简单的加密或环境变量）
+- 网关 API_KEY 验证（可选）
+- 请求日志中的敏感信息脱敏（API Key、Token 等）
+
+## Risks / Trade-offs
+
+### Risk: 协议差异导致适配复杂
+**Mitigation**: 先实现核心协议（OpenAI、Anthropic），其他协议逐步添加
+
+### Risk: SQLite 并发写入性能
+**Mitigation**: 
+- 日志写入使用批量插入
+- 考虑使用 WAL 模式提升并发性能
+- 如果性能不足，后续可迁移到 PostgreSQL
+
+### Risk: CLI 工具打包体积
+**Mitigation**: 
+- 使用 Next.js standalone 输出
+- 排除不必要的依赖
+- 考虑使用 pkg 或类似工具打包为单文件
+
+### Trade-off: 单机部署 vs 分布式
+**Decision**: 先实现单机部署，满足 MVP 需求，后续可扩展
+
+## Migration Plan
+N/A - 全新项目，无需迁移
+
+## Open Questions
+1. API Key 加密方案：使用环境变量还是数据库加密？
+2. 日志保留策略：是否需要自动清理旧日志？
+3. 模型列表自动拉取：是否需要定时刷新？
+4. 网关启动时的端口冲突处理？

package/openspec/changes/init-api-gateway/proposal.md

@@ -0,0 +1,30 @@
+# Change: 初始化 API 网关项目
+
+## Why
+需要一个统一的 API 网关来管理和路由多个 AI 模型供应商（Anthropic、OpenAI、Gemini 等），为 Claude、Zcode、Alma 等客户端软件提供统一的接口。该网关需要支持灵活的模型配置、请求日志记录和可视化管理界面，最终发布为 npm CLI 工具以便于部署和使用。
+
+## What Changes
+- **新增 API 网关核心功能**：支持多种协议（Anthropic、OpenAI、Gemini），统一路由和转发请求
+- **新增模型供应商管理**：支持添加、配置多个模型供应商（baseUrl、API Key）
+- **新增模型管理功能**：支持手动添加模型和自动拉取模型列表
+- **新增 Web 管理界面**：基于 Next.js + Tailwind CSS 的前端界面，用于配置网关、管理供应商和模型
+- **新增请求日志系统**：记录所有 API 请求，提供可视化的日志查看界面（请求头、query、body、response）
+- **新增 CLI 工具**：将网关打包为 Node.js CLI 工具，支持通过 npm 发布和安装
+- **新增数据库存储**：使用 SQLite3 存储配置和日志数据
+
+## Impact
+- Affected specs: 
+  - `api-gateway` (新增核心网关功能)
+  - `model-provider` (新增供应商管理)
+  - `model-management` (新增模型管理)
+  - `web-ui` (新增 Web 管理界面)
+  - `request-logging` (新增请求日志)
+  - `cli-tool` (新增 CLI 工具)
+- Affected code: 
+  - 全新项目，无现有代码影响
+- 技术栈：
+  - Next.js (前端框架)
+  - Tailwind CSS (样式)
+  - SQLite3 (数据库)
+  - Node.js (后端运行时)
+  - npm (包管理)

package/openspec/changes/init-api-gateway/specs/api-gateway/spec.md

@@ -0,0 +1,42 @@
+## ADDED Requirements
+
+### Requirement: API 网关核心功能
+The system SHALL provide an API gateway that routes requests from clients (Claude, Zcode, Alma) to appropriate AI model providers based on model configuration.
+
+#### Scenario: 启动网关服务
+- **WHEN** 用户执行 `api-gateway start` 命令
+- **THEN** 网关服务器启动并监听配置的端口
+- **AND** Web 管理界面同时启动
+
+#### Scenario: 接收客户端请求
+- **WHEN** 客户端（Claude/Zcode/Alma）向网关发送 API 请求
+- **THEN** 网关接收请求并解析模型标识符
+- **AND** 根据模型配置路由到对应的供应商 API
+
+#### Scenario: 转发请求到供应商
+- **WHEN** 网关确定目标供应商和模型
+- **THEN** 使用对应的协议适配器转发请求
+- **AND** 将供应商的响应返回给客户端
+
+#### Scenario: 处理请求错误
+- **WHEN** 供应商 API 返回错误或超时
+- **THEN** 网关返回适当的错误响应给客户端
+- **AND** 错误信息记录到日志中
+
+### Requirement: 协议支持
+The system SHALL support multiple AI model protocols including Anthropic, OpenAI, and Gemini.
+
+#### Scenario: OpenAI 协议请求
+- **WHEN** 客户端请求使用 OpenAI 模型
+- **THEN** 网关使用 OpenAI 协议适配器转发请求
+- **AND** 请求格式符合 OpenAI API 规范
+
+#### Scenario: Anthropic 协议请求
+- **WHEN** 客户端请求使用 Anthropic 模型
+- **THEN** 网关使用 Anthropic 协议适配器转发请求
+- **AND** 请求格式符合 Anthropic API 规范
+
+#### Scenario: Gemini 协议请求
+- **WHEN** 客户端请求使用 Gemini 模型
+- **THEN** 网关使用 Gemini 协议适配器转发请求
+- **AND** 请求格式符合 Gemini API 规范

package/openspec/changes/init-api-gateway/specs/cli-tool/spec.md

@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: CLI 工具
+The system SHALL be packaged as a Node.js CLI tool that can be installed via npm.
+
+#### Scenario: 安装 CLI 工具
+- **WHEN** 用户执行 `npm install -g api-gateway`（或包名）
+- **THEN** CLI 工具安装到全局
+- **AND** 可以通过命令行执行 `api-gateway` 命令
+
+#### Scenario: 启动网关
+- **WHEN** 用户执行 `api-gateway start`
+- **THEN** 网关服务器启动
+- **AND** Web 管理界面启动
+- **AND** 显示启动信息和访问地址
+
+#### Scenario: 查看帮助信息
+- **WHEN** 用户执行 `api-gateway --help` 或 `api-gateway -h`
+- **THEN** 显示命令使用说明
+- **AND** 列出所有可用命令和选项
+
+#### Scenario: 配置命令（可选）
+- **WHEN** 用户执行 `api-gateway config set port 3000`
+- **THEN** 配置项保存
+- **AND** 下次启动时使用新配置
+
+### Requirement: npm 发布
+The system SHALL be published to npmjs registry.
+
+#### Scenario: 发布到 npm
+- **WHEN** 开发者执行 `npm publish`
+- **THEN** 包发布到 npmjs
+- **AND** 其他用户可以通过 npm 安装
+- **AND** package.json 配置正确（bin 字段、版本号等）
+
+#### Scenario: 包信息配置
+- **WHEN** 用户查看 npm 包信息
+- **THEN** 显示正确的包名、版本、描述
+- **AND** 包含 README.md 说明文档
+- **AND** 包含必要的元数据（author、license 等）