内容
# 代理技能 — 后端 API
代理机构管理平台，具备多代理系统、自定义资源（技能、规则、代理、工作流）和MCP（模型上下文协议）用于与CLI工具集成。
---
## 技术栈
- **运行时**: Node.js + TypeScript
- **框架**: NestJS 11 (六边形架构 + CQRS)
- **数据库**: PostgreSQL (TypeORM 0.3)
- **缓存/会话**: Redis (ioredis)
- **认证**: Google OAuth 2.0 + JWT（访问 + 刷新令牌）
- **API 文档**: Swagger UI (`/api`)
- **MCP**: `@modelcontextprotocol/sdk`（stdio + SSE）
---
## 快速入门
```bash
# 安装依赖
pnpm install
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写数据库、JWT 密钥、Google OAuth 凭证
# Docker（PostgreSQL + Redis）
pnpm run docker:up
# 执行数据库迁移
pnpm run db:migrate
# 开发模式
pnpm run start:dev
```
服务器启动在 `http://localhost:8004`。
---
## 目录结构
```
src/
├── core/ # 领域 + 端口（干净架构）
│ ├── agents/ # 17 个专业代理
│ ├── domain/ # 接口、实体、令牌
│ ├── infrastructure/ # 数据库、适配器、MCP 控制器
│ ├── presentation/ # REST 控制器（健康检查、规则、MCP、代理、会话）
│ └── skills/ # Hermes 技能系统
├── modules/
│ ├── auth/ # Google OAuth + JWT（访问/刷新）
│ ├── agencies/ # 机构 CRUD
│ ├── agency-resources/ # 技能、规则、代理、工作流，按机构划分
│ ├── users/ # 用户（按 IP 查找）
│ ├── sessions/ # MCP 会话
│ ├── issues/ # 问题管理
│ ├── projects/ # 项目检测
│ ├── contexts/ # 项目上下文
│ ├── plans/ # 工作计划
│ ├── memory/ # 记忆系统
│ └── agency-agents/ # 代理目录
├── agents/ # 代理实现
├── rules/ # 代码规则（.rule.ts 文件）
├── shared/ # 中间件、实用工具、常量
├── mcp-server.ts # MCP stdio 服务器
├── mcp-http-server.ts # MCP HTTP 服务器
└── main.ts # NestJS 启动
```
---
## 环境变量
```env
# 服务器
PORT=8004
CORS_ORIGIN=http://localhost:4200
# 数据库
DB_URL=postgres://user:password@localhost:5432/agent_skills?sslmode=disable
DB_SYNCHRONIZE=false
# Redis
REDIS_URL=redis://localhost:6379/0
# JWT
JWT_ACCESS_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-other-secret-here
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d
# Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
```
查看 `.env.example` 文件，了解所有可用变量（Exa AI、Context7、ChromaDB 等）。
---
## 脚本
```bash
# 开发模式
pnpm run start:dev # 热重载
pnpm run start:debug # 调试模式
# 生产环境
pnpm run build # 完整构建
pnpm run start:prod # 运行 dist/main
# 数据库
pnpm run db:migrate # 执行待处理迁移
pnpm run db:migrate:revert # 回滚最后一次迁移
pnpm run db:generate # 从实体更改生成迁移
# MCP
pnpm run start:mcp # MCP stdio 服务器
pnpm run start:mcp-http # MCP HTTP 服务器
pnpm run build:mcp # 构建 MCP stdio
pnpm run build:mcp-http # 构建 MCP HTTP
# 测试
pnpm run test # 单元测试
pnpm run test:e2e # 端到端测试
pnpm run test:cov # 覆盖率
# Docker
pnpm run docker:up # 启动服务
pnpm run docker:down # 停止服务
pnpm run docker:logs # 查看日志
# 校验
pnpm run lint # ESLint + 自动修复
pnpm run typecheck # 类型检查，不发出错误
# CLI 代理
pnpm run agent:setup-gemini # 配置 Gemini MCP
pnpm run mcp:update-claude # 更新 Claude Code 配置
```
---
## 主要端点
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/health` | 健康检查 |
| `GET` | `/api` | Swagger UI |
| `GET` | `/mcp/sse` | MCP SSE 端点 |
| `POST` | `/mcp/message` | MCP 消息端点 |
### 认证
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/api/auth/login/google` | Google 登录 |
| `GET` | `/api/auth/refresh` | 刷新访问令牌 |
| `POST` | `/api/auth/logout` | 注销 |
### 机构
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/v1/agency` | 创建机构 |
| `GET` | `/v1/agency/by-user/:userId` | 获取用户机构 |
| `GET` | `/v1/agency/:id` | 获取机构 ID |
| `PATCH` | `/v1/agency/:id` | 更新机构 |
| `DELETE` | `/v1/agency/:id` | 删除机构 |
### 机构资源
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `POST` | `/v1/agency/:agencyId/skills` | 创建技能 |
| `GET` | `/v1/agency/:agencyId/skills` | 列出技能 |
| `GET` | `/v1/agency/:agencyId/skills/:id` | 获取技能 ID |
| `PUT` | `/v1/agency/:agencyId/skills/:id` | 更新技能 |
| `DELETE` | `/v1/agency/:agencyId/skills/:id` | 删除技能 |
| | | *(类似地适用于 `/rules`、`/agents`、`/workflows`)* |
### 机构成员
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/v1/agency/:id/members` | 列出成员 |
| `POST` | `/v1/agency/:id/members` | 添加成员 |
| `DELETE` | `/v1/agency/:id/members/:userId` | 删除成员 |
### 用户
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| `GET` | `/v1/users/search?q=` | 按电子邮件/名称搜索用户 |
| `GET` | `/v1/users/:id` | 获取用户 ID |
---
## 代理（17）
| 代理 | 责任 |
|--------|----------------|
| **RouterAgent** | 主协调器，检测意图并委托 |
| **SearchAgent** | BM25 规则搜索 |
| **IdentityAgent** | MCP 身份和前缀 |
| **RulesAgent** | 规则列表和管理 |
| **CodeAgent** | 代码生成 |
| **ArchitectureAgent** | 架构验证 |
| **AnalysisAgent** | 代码分析 |
| **MetricsAgent** | 指标和跟踪 |
| **PMAgent** | 项目管理 |
| **IssueWorkflowAgent** | 问题工作流 |
| **GitHubAgent** | GitHub 集成 |
| **FrontendArchitectureAgent** | 前端架构 |
| **WebSearchAgent** | 网络搜索（Exa AI） |
| **Context7Agent** | 库文档 |
| **ContextAgent** | 项目上下文 |
| **ProjectHistoryAgent** | 项目历史 |
| **GraphifyAgent** | 代码可视化 |
| **ObsidianAgent** | Obsidian 集成 |
---
## MCP（模型上下文协议）
MCP 服务器通过两个传输层公开工具：
- **stdio** (`pnpm run start:mcp`)：用于本地 CLI 集成（Claude Code、Gemini、OpenCode）
- **SSE** (`/mcp/sse` + `/mcp/message`)：用于 Web 和远程集成
### MCP 工具
| 工具 | 描述 |
|------|-------------|
| `session_init_auto` | 使用项目上下文初始化 MCP 会话 |
| `list_agency_skills` | 列出活动机构的技能 |
| `get_skill_detail` | 获取特定技能的详细信息 |
| `invoke_skill` | 执行技能 |
---
## 架构
- **六边形（端口和适配器）**：业务逻辑与基础设施隔离
- **CQRS**：使用 `@nestjs/cqrs` 分离命令和查询
- **仓库模式**：领域接口，基础设施实现
- **双 JWT**：访问令牌（15 分钟）在本地存储，刷新令牌（7 天）在 httpOnly cookie 中
- **基于 IP 的身份验证**：用于无 cookie 可用的 SSE/MCP 连接
---
## 其他文档
- `doc/ARCHITECTURE.md` — 完整系统架构
- `doc/MCP-CONFIG.md` — 工具 MCP 配置
- `doc/IMPLEMENTATION_STATUS.md` — 实现状态
