# gw-ai-agent-framework

**Repository Path**: g_w/gw-ai-agent-framework

## Basic Information

- **Project Name**: gw-ai-agent-framework
- **Description**: 一个基于Vue 3的完整AI Agent开发框架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Agent, AI

## README

# gw AI Agent Framework

一个基于 **Vue 3 + TypeScript + Express** 的完整 AI Agent 开发框架，集成了 **Spec 规范**、**Skills 技能系统**、**MCP (Model Context Protocol)**、**Agent Planner** 以及 **Skill 智能路由** 等核心能力，支持流式对话、SQLite 持久化、API Key 鉴权、Docker 部署与 GitHub Actions CI。

## ✨ 特性

- **📋 Spec 系统**：可视化配置 Agent 行为规范（system prompt / constraints / model / skills / mcpServers），内置 6 大类别标签页与 JSON 编辑器（含格式化、智能缩进、Trailing-comma 容错）。
- **🎯 Skills 技能系统**：模块化技能管理，支持元数据与内容两层架构，提供渐进式披露与按需加载。
- **🧭 Skill 智能路由**：两层匹配机制（Fast Path 关键词加权 + Deep Path LLM 语义精排），自动为用户请求选择最相关的 Skill。
- **🧠 Agent Planner**：多步骤任务规划器（Thinking → Skills → Tools → Response），支持「深度思考」开关，可选择性开启前两步的 LLM thinking。
- **💬 流式对话 (SSE)**：基于 Server-Sent Events 的打字机效果流式输出，首个 chunk 到达前显示 loading 动画。
- **🔌 MCP Client**：完整的 MCP 客户端实现，支持 `stdio` / `SSE` / `WebSocket` 三种传输协议，附带**心跳检测**与**指数退避重连**。
- **🗄 SQLite 持久化**：聊天记录通过 `sql.js`（纯 JS 实现）持久化，并提供 JSON 文件降级方案；事务性写入保证数据一致性。
- **🔐 API Key 鉴权**：内置用户注册 / 登录 / API Key 管理，使用 PBKDF2-SHA256（10000 次迭代 + 16 字节 salt）哈希密码，SHA-256 存储 Key。
- **🐳 Docker 化部署**：多阶段 Dockerfile + docker-compose，使用命名卷持久化 SQLite 数据，内置健康检查。
- **🧪 Vitest 单元测试**：服务层 + API 路由的覆盖（密码哈希、Key 生成、CRUD、权限隔离等）。
- **🔧 GitHub Actions CI**：Node 20.x / 22.x 矩阵构建、类型检查、单元测试、产物上传。

## 🏗️ 技术栈

### 前端 (client/)
- Vue 3（Composition API）
- TypeScript、Vite 5
- Pinia 状态管理、Vue Router 4
- Axios、marked (Markdown 渲染)、yaml

### 后端 (server/)
- Node.js + Express
- TypeScript、tsx（开发）、sql.js（SQLite 纯 JS 实现）
- dotenv（多路径兜底加载）、body-parser、cors
- WebSocket、Eventsource、uuid

### 共享 (shared/)
- 统一 TypeScript 类型定义（Agent / Spec / Skill / MCP）
- MCP 协议类型与 Skills 格式标准

### 测试 / 工程化
- Vitest + Supertest
- Docker / docker-compose
- GitHub Actions

## 📦 项目结构

```
agent-test/
├── client/                      # Vue 3 前端
│   ├── src/
│   │   ├── services/            # AgentPlanner / AgentEngine / SkillRouter / MCPProtocol / transports
│   │   ├── stores/              # Pinia stores: authStore / chatStore / mcpStore / skillStore / specStore
│   │   ├── views/               # 页面：AgentChat / MCPManager / SkillManager / SpecManager / Login
│   │   ├── router/              # 路由
│   │   ├── App.vue / main.ts / style.css
│   └── package.json
├── server/                      # Express 后端
│   ├── src/
│   │   ├── api/                 # 路由：auth / chat / mcp / skills / spec
│   │   ├── middleware/          # 鉴权中间件
│   │   ├── services/            # auth / database(sqlite) / llm / mcpProxy
│   │   └── index.ts             # 入口（.env 多路径加载、健康检查、SSE）
│   ├── tests/                   # Vitest 单元测试
│   ├── data/db/                 # SQLite 数据库目录（auth.sqlite / chat.sqlite）
│   └── package.json
├── shared/                      # 前后端共享类型
│   └── src/types/                # agent / mcp / skill / spec
├── skills/                      # 可扩展技能库（code-skill / test / ...）
├── data/
│   ├── mcp-servers/             # MCP Server 配置（JSON）
│   └── specs/                   # Agent Spec 配置（JSON）
├── .github/workflows/ci.yml     # GitHub Actions
├── Dockerfile / docker-compose.yml
└── package.json                 # npm workspaces 根配置
```

## 🚀 快速开始

### 前置要求

- Node.js **>= 20**（推荐 LTS）
- npm >= 9
- 可选：Docker / Docker Compose

### 1. 克隆并安装依赖

```bash
git clone <repo-url> && cd ai-agent-framework
npm install
```

项目使用 **npm workspaces**，一次 `npm install` 会同时安装 `client` / `server` / `shared` 的依赖。

### 2. 配置环境变量

```bash
# 复制示例（server/.env.example 已随仓库提供）
cp server/.env.example server/.env
```

关键变量：

| 变量 | 说明 |
| --- | --- |
| `PORT` | 后端端口，默认 `3000` |
| `NODE_ENV` | `development` / `production` |
| `DASHSCOPE_API_KEY` | **必填**，用于调用 qwen / DashScope LLM |
| `MCP_DEFAULT_TIMEOUT` | MCP 调用超时，默认 30000ms |
| `MCP_MAX_CONNECTIONS` | MCP 最大连接数 |
| `LOG_LEVEL` | 日志级别 |

> 注：`DASHSCOPE_API_KEY` 未设置时，启动日志会给出醒目警告，LLM 相关请求将全部失败。

### 3. 启动开发模式

```bash
# 同时启动前端 + 后端
npm run dev

# 分别启动
npm run dev:client   # 仅前端 (Vite, http://localhost:5173)
npm run dev:server   # 仅后端 (Express, http://localhost:3000)
```

- 前端：<http://localhost:5173>
- 后端：<http://localhost:3000>
- 健康检查：`GET /health`
- API Key 自检：`POST /api/chat/test-key`

首次进入会要求注册账号，随后进入主界面选择或创建 Spec 即可开始对话。

### 4. 生产构建

```bash
npm run build          # 依次构建 shared → server → client
npm start              # node server/dist/index.js
```

## 🐳 Docker 部署

### 使用 docker-compose（推荐）

```bash
# 构建并启动（含 SQLite 数据卷持久化、健康检查、日志滚动）
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 停止
docker-compose down
```

容器启动后访问 <http://localhost:3000>。数据（SQLite / specs / skills）通过命名卷 `ai-agent-db` / `ai-agent-specs` / `ai-agent-skills` 持久化。

### 手动构建镜像

```bash
docker build -t ai-agent-framework:latest .
docker run -d \
  --name ai-agent-framework \
  -p 3000:3000 \
  -e DASHSCOPE_API_KEY=your-key \
  -v ai-agent-db:/app/server/data/db \
  ai-agent-framework:latest
```

## 📖 核心概念

### Spec（规范）
Spec 是 Agent 的完整配置单元：

```ts
interface AgentSpec {
  id: string;
  name: string;
  model: ModelConfig;       // provider / model / baseUrl / apiKey / temperature ...
  behavior: BehaviorRules;  // systemPrompt / constraints / deepThinking 默认值
  skills: SkillReference[]; // 启用的 skills 列表
  mcpServers: MCPServerConfig[]; // 连接的 MCP servers
}
```

前端提供 **SpecManager** 可视化编辑器，支持基础信息、模型配置、行为规则、Skills、MCP Server、Preview/JSON 六大类别标签页切换，并在保存前自动做结构化校验。

### Skills（技能）
Skills 采用「两层架构」：
- **发现层**：YAML frontmatter 元数据（name / description / triggerKeywords / tags / estimatedTokens），启动时加载用于路由。
- **内容层**：`SKILL.md` 详细指令，按需加载注入 system prompt。

### Skill Router（智能路由）
- **Fast Path**：基于 triggerKeywords / tags / name/description / category 的加权关键词匹配，毫秒级。
- **Deep Path**：当 `deepThinking` 开启时，可选 LLM 精排（严格 JSON 输出，失败自动回退 Fast Path）。

### Agent Planner
将用户请求自动拆解为 4 步：

1. **Think** — 分析意图，生成候选 skill / tool 调用计划。
2. **Skills** — 通过 Skill Router 匹配最相关的 skill。
3. **Tools** — 调用所需 MCP tools（如存在）。
4. **Response** — 汇总生成最终回答（SSE 流式输出）。

`deepThinking` 开关控制第 1、2 步是否调用 LLM thinking。Planner 支持中途取消、步骤跳过时自动降级，不会因单个 tool 缺失 `toolName` 而中断整个计划。

### MCP（Model Context Protocol）
支持三大原语：**Tools / Resources / Prompts**，传输方式：
- `stdio`（本地进程，使用 MCP 官方 SDK 如 `@modelcontextprotocol/server-filesystem`）
- `SSE`（单向流，对接远程 MCP Server）
- `WebSocket`（双向通信）

MCP 层实现了**心跳检测**与**指数退避重连**（1s → 30s，最多 10 次），并在组件卸载时（`AgentChat.onBeforeUnmount`、`main.ts` `beforeunload`）统一清理定时器与 pending 请求，彻底杜绝接口泄漏。

## 🔧 API 文档

### 认证（无需 API Key）
```
POST /api/auth/register            注册
POST /api/auth/login               登录（返回 token 与用户信息）
GET  /api/auth/me                  获取当前用户
POST /api/auth/keys                生成 API Key（仅返回一次明文）
GET  /api/auth/keys                列出已持有 Key
DELETE /api/auth/keys/:id          撤销 Key
```

### Spec / Skills（需 `Authorization: Bearer <key>` 或 `X-API-Key`）
```
GET    /api/spec / :id
POST   /api/spec
PUT    /api/spec/:id
DELETE /api/spec/:id

GET    /api/skills                  # 元数据列表
GET    /api/skills/:id             # 完整 SKILL.md
POST   /api/skills                 # 上传
```

### Chat（流式）
```
POST  /api/chat/stream             # SSE 流式回答（支持 planner / non-planner 两种模式）
POST  /api/chat/test-key           # DashScope API Key 健康检查
GET   /api/chat/history?specId=:id # 拉取历史记录（SQLite）
DELETE /api/chat/history?specId=:id
```

### MCP
```
GET   /api/mcp/servers             # 列出已配置 servers
POST  /api/mcp/connect             # 连接 server（含心跳）
POST  /api/mcp/disconnect
POST  /api/mcp/call-tool           # 工具调用
GET   /api/mcp/proxy/messages      # 代理轮询（stdio 传输的消息通道）
```

### 健康检查
```
GET  /health
```

## 🛡 鉴权机制

除 `/api/auth/*` 外，所有 API 均需通过以下任一方式携带 API Key：

- `Authorization: Bearer <api-key>`
- `X-API-Key: <api-key>`

服务端使用 **PBKDF2-SHA256**（10000 次迭代 + 16 字节 salt）哈希用户密码，使用 **SHA-256** 存储 API Key 哈希值。Key 明文仅在 `POST /api/auth/keys` 成功响应中返回一次，之后不可再查询。

## 🗄 数据持久化

- **主要存储**：`server/data/db/*.sqlite`（sql.js 事务性 CRUD）
  - `listMessagesBySpec / replaceMessagesBySpec / appendMessage / clearMessagesBySpec`
- **降级存储**：`chat-history.json`（JSON 文件，自动 fallback）
- **会话保护**：`isRestoring` 锁 + `isSessionActive` 双标志位防止刷新/卸载时空数组覆盖已持久化历史；流式输出期间保存节流至 500ms。

## 🧪 测试

使用 **Vitest + Supertest**，每个用例使用独立 SQLite 目录（`server/data/test-<unique-id>/`），自动清理：

```bash
cd server
npm test                  # 一次性运行
npm run test:watch        # watch 模式
npm run test:coverage     # 覆盖率报告
```

覆盖：
- `auth.service.test.ts`：密码哈希、Key 生成、用户 CRUD、Key CRUD、多用户权限隔离
- `auth.api.test.ts`：register / login / me / keys 路由集成测试

## 🔁 CI（GitHub Actions）

Push / PR 到 `main` / `master` 分支时触发：
- Node 20.x / 22.x 矩阵（`fail-fast: false`）
- `npm ci` 严格依赖安装
- shared → server（tsc + vitest）→ client（vue-tsc + vite build）
- 在 Node 20 下上传 `client/dist` 与 `server/dist` 作为 artifact（保留 7 天）

## 📁 目录约定

- `data/mcp-servers/*.json` —— 可提交的 MCP 配置；`*.local.json` / `*.secrets.json` / `*.private.json` 已加入 `.gitignore`
- `data/specs/*.json` —— 可提交的 Spec 模板（建议保留 `*.example.json`）
- `server/data/db/*.sqlite` —— 运行时数据，不提交
- `server/data/test-*/` —— Vitest 隔离数据库，运行时生成不提交
- `skills/<name>/SKILL.md` —— 自定义技能目录

## 📄 License

MIT License

## 🤝 贡献

欢迎提交 Issue 与 Pull Request。

## 📮 联系方式

如有问题或建议，请提交 Issue。