caoxiaozhu/X-Agents
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5ea6f0d31fc4b5b593c56053a081f2a4b86b83aa
X-Agents/docs/ARCHITECTURE.md
DESKTOP-72TV0V4\caoxiaozhu b2bc9988a9 feat: 重构前后端架构，添加Go后端和Python Agent服务 
- 新增 Go 语言后端服务(server/)，包含用户认证、Agent管理、数据库连接等API
- 新增 Python Agent 服务(agent/)，实现Agent核心逻辑和工具集
- 前端从原生HTML迁移到Vue.js框架(web/src/)
- 添加 Docker Compose 支持(docker-compose.yml)
- 添加项目架构文档(docs/ARCHITECTURE.md)
- 添加环境变量示例(.env.example)和本地启动脚本(start-local.ps1)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 16:39:42 +08:00

836 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# X-Agents 智能体平台架构设计
## 一、整体架构
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户层 │
│ Web / App / API Consumer │
└─────────────────────────────────┬───────────────────────────────────────────┘
│ HTTP / WebSocket
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Go API Gateway │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ • HTTP Server (Gin) • 认证鉴权 (JWT) ││
│ │ • 路由管理 • 限流熔断 ││
│ │ • 业务逻辑 • 日志监控 ││
│ │ • 数据库操作 • 权限控制 (RBAC) ││
│ └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────┬───────────────────────────────────────────┘
│ HTTP JSON API
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Python Agent Engine │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ • FastAPI Server • Agent Core (LangChain/AutoGen) ││
│ │ • LLM Adapter • Tool Registry (白名单) ││
│ │ • Memory Manager • Sandbox Executor (沙盒) ││
│ │ • RAG Pipeline • Audit Logger ││
│ └─────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 二、系统分层
### 2.1 Go 后端层 (server/)
```
server/ # Go API Gateway 服务
├── cmd/api/ # 程序入口
│ └── main.go
├── internal/
│ ├── config/ # 配置管理
│ │ └── config.go
│ ├── handler/ # HTTP处理器
│ │ ├── auth_handler.go # 认证接口
│ │ ├── chat_handler.go # 聊天接口
│ │ └── approval_handler.go # 审批接口
│ ├── service/ # 业务逻辑
│ │ ├── auth_service.go
│ │ ├── chat_service.go
│ │ └── approval_service.go
│ ├── repository/ # 数据访问层
│ │ ├── user_repo.go
│ │ ├── agent_repo.go
│ │ └── audit_repo.go
│ ├── middleware/ # 中间件
│ │ └── auth.go
│ └── model/ # 数据模型
│ ├── user.go
│ ├── agent.go
│ └── audit.go
├── config/ # 配置文件
│ └── config.yaml
├── Dockerfile
├── go.mod
└── go.sum
```
### 2.2 Python Agent 层 (agent/)
```
agent/ # Python Agent Engine
├── app/
│ ├── main.py # FastAPI入口
│ ├── api/
│ │ └── routes.py # API路由
│ ├── agent/
│ │ ├── core/
│ │ │ ├── agent.py # Agent管理器
│ │ │ └── executor.py # Agent执行器
│ │ ├── tools/
│ │ │ ├── registry.py # 工具注册表(白名单)
│ │ │ └── impl/ # 工具实现
│ │ │ ├── search.py
│ │ │ ├── calculator.py
│ │ │ └── time_tool.py
│ │ └── memory/
│ │ └── session.py # 会话管理
│ ├── llm/
│ │ └── factory.py # LLM工厂
│ └── security/
│ ├── audit.py # 审计日志
│ └── approval.py # 审批服务
├── requirements.txt
├── Dockerfile
└── pyproject.toml
```
### 2.3 根目录结构
```
X-Agents/
├── server/ # Go API Gateway
├── agent/ # Python Agent Engine
├── web/ # 前端 (Vue.js)
├── docs/
│ └── ARCHITECTURE.md # 架构文档
├── docker-compose.yml # 容器编排
├── .env.example # 环境变量模板
└── README.md
│ ├── service/ # 业务逻辑
│ │ ├── chat_service.go
│ │ ├── agent_service.go
│ │ └── approval_service.go # 审批服务
│ ├── repository/ # 数据访问层
│ │ ├── user_repo.go
│ │ ├── agent_repo.go
│ │ └── audit_repo.go
│ ├── middleware/ # 中间件
│ │ ├── auth.go # 认证中间件
│ │ ├── rbac.go # 权限中间件
│ │ └── audit.go # 审计中间件
│ ├── client/ # 外部服务客户端
│ │ └── python_client.go # Python服务HTTP客户端
│ └── model/ # 数据模型
│ ├── user.go
│ ├── agent.go
│ └── audit.go
├── pkg/
│ ├── utils/ # 工具函数
│ └── errors/ # 错误定义
└── go.mod
```
### 2.2 Python AI 层 (智能逻辑)
```
python/
├── app/
│ ├── main.py # FastAPI入口
│ ├── api/
│ │ ├── routes.py # 路由定义
│ │ └── dependencies.py # 依赖注入
│ ├── agent/
│ │ ├── core/
│ │ │ ├── agent.py # Agent核心
│ │ │ ├── executor.py # 执行器
│ │ │ └── memory.py # 记忆管理
│ │ ├── tools/
│ │ │ ├── registry.py # 工具注册表
│ │ │ ├── base.py # 工具基类
│ │ │ ├── security.py # 安全检查
│ │ │ └── impl/ # 具体工具实现
│ │ │ ├── search.py
│ │ │ ├── calculator.py
│ │ │ ├── database.py
│ │ │ └── sandbox.py # 沙盒执行
│ │ └── sandbox/
│ │ ├── docker_sandbox.py
│ │ └── wasm_sandbox.py
│ ├── llm/
│ │ ├── factory.py # LLM工厂
│ │ ├── openai_adapter.py
│ │ ├── anthropic_adapter.py
│ │ └── base.py
│ ├── rag/
│ │ ├── vector_store.py # 向量存储
│ │ ├── retriever.py # 检索器
│ │ └── pipeline.py # RAG流程
│ └── security/
│ ├── permission.py # 权限检查
│ ├── approval.py # 审批管理
│ └── audit.py # 安全审计
├── requirements.txt
└── pyproject.toml
```
---
## 三、通信机制
### 3.1 HTTP API 通信
```
┌──────────────────┐ HTTP POST ┌──────────────────┐
│ │ ─────────────▶ │ │
│ Go Service │ JSON Request │ Python Service │
│ (Port: 8080) │ │ (Port: 8081) │
│ │ ◀───────────── │ │
└──────────────────┘ JSON Response └──────────────────┘
```
#### 接口设计
**1. Agent 聊天接口**
```
POST /api/v1/agent/chat
Content-Type: application/json
Authorization: Bearer <token>
Request:
{
"agent_id": "agent_001",
"message": "帮我查询用户数据",
"session_id": "session_xxx",
"context": {} // 额外上下文
}
Response:
{
"reply": "查询结果...",
"session_id": "session_xxx",
"tools_used": ["query_database"],
"metadata": {}
}
```
**2. 工具执行审批接口**
```
POST /api/v1/tool/approve
Request:
{
"request_id": "req_001",
"tool_name": "execute_sql",
"params": {"sql": "SELECT * FROM users"},
"reason": "用户查询自己的订单",
"approved": true // true=批准, false=拒绝
}
```
**3. 工具执行状态查询**
```
GET /api/v1/tool/request/{request_id}
Response:
{
"status": "pending|approved|rejected|completed",
"tool_name": "execute_sql",
"created_at": "2024-01-01T00:00:00Z",
"result": null // 如果已完成
}
```
### 3.2 Go → Python 客户端
```go
// internal/client/python_client.go
package client
type PythonAgentClient struct {
baseURL string
client *http.Client
}
type ChatRequest struct {
AgentID string `json:"agent_id"`
Message string `json:"message"`
SessionID string `json:"session_id"`
Context map[string]interface{} `json:"context"`
}
type ChatResponse struct {
Reply string `json:"reply"`
SessionID string `json:"session_id"`
ToolsUsed []string `json:"tools_used"`
Metadata map[string]interface{} `json:"metadata"`
}
// Chat 调用Python Agent服务
func (c *PythonAgentClient) Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error) {
// 1. 构建请求
// 2. 添加超时
// 3. 发送请求
// 4. 处理响应
// 5. 错误处理
}
```
---
## 四、沙盒安全机制
### 4.1 安全架构总览
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 安全控制层 │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌──────────┐ │
│ │ 权限管理 │ │ 工具分级 │ │ 人工审批 │ │ 审计日志 │ │
│ │ (RBAC) │ │ (白名单) │ │ (Approval) │ │ (Audit) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └────┬─────┘ │
└─────────┼─────────────────┼─────────────────┼─────────────────┼────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────────────┐
│ Agent 执行层 │
│ │
│ User Request ─▶ Permission Check ─▶ Tool Lookup ─▶ Execute ─▶ Result │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ [Need Approval] ──▶ [Pending Queue] ──▶ [Notify] │
└─────────────────────────────────────────────────────────────────────────┘
```
### 4.2 工具安全等级
```python
# python/app/agent/tools/security.py
from enum import Enum
from dataclasses import dataclass
from typing import List, Callable
class SecurityLevel(Enum):
"""工具安全等级"""
SAFE = "safe" # 安全操作：搜索、计算、读取公开数据
REVIEW = "review" # 需要审核：修改数据、发送消息
DANGER = "danger" # 危险操作：删除数据、执行代码、敏感API
@dataclass
class ToolMetadata:
"""工具元数据"""
name: str
description: str
security_level: SecurityLevel
require_approval: bool # 是否需要人工审批
allowed_roles: List[str] # 允许调用的角色
rate_limit: int # 调用频率限制
timeout: int # 超时时间(秒)
class ToolSecurity:
"""工具安全管理"""
# 安全等级阈值
APPROVAL_THRESHOLD = SecurityLevel.REVIEW
@staticmethod
def check_permission(tool: ToolMetadata, user_role: str) -> bool:
"""检查用户权限"""
if user_role in tool.allowed_roles:
return True
return False
@staticmethod
def need_approval(tool: ToolMetadata) -> bool:
"""判断是否需要审批"""
return tool.security_level.value >= ToolSecurity.APPROVAL_THRESHOLD.value
```
### 4.3 工具注册与执行
```python
# python/app/agent/tools/registry.py
from typing import Dict, Callable, Any
from .security import ToolMetadata, SecurityLevel
class ToolRegistry:
"""工具注册表 - 白名单机制"""
def __init__(self):
self._tools: Dict[str, tuple[Callable, ToolMetadata]] = {}
def register(
self,
name: str,
func: Callable,
security_level: SecurityLevel = SecurityLevel.SAFE,
require_approval: bool = False,
allowed_roles: List[str] = None,
description: str = ""
):
"""注册工具到白名单"""
metadata = ToolMetadata(
name=name,
description=description,
security_level=security_level,
require_approval=require_approval or security_level == SecurityLevel.REVIEW,
allowed_roles=allowed_roles or ["user", "admin"],
rate_limit=100,
timeout=30
)
self._tools[name] = (func, metadata)
def get_tool(self, name: str) -> tuple[Callable, ToolMetadata]:
"""获取工具（必须在白名单中）"""
if name not in self._tools:
raise ValueError(f"Tool '{name}' not found in whitelist")
return self._tools[name]
def list_tools(self) -> List[ToolMetadata]:
"""列出所有可用工具"""
return [meta for _, meta in self._tools.values()]
```
### 4.4 沙盒执行
```python
# python/app/agent/tools/sandbox/docker_sandbox.py
import subprocess
import tempfile
import shutil
import os
from typing import Any, Dict
class DockerSandbox:
"""Docker沙盒执行环境"""
def __init__(self, image: str = "python-sandbox:latest", timeout: int = 30):
self.image = image
self.timeout = timeout
def execute(self, code: str, language: str = "python") -> Dict[str, Any]:
"""在沙盒中执行代码"""
# 1. 创建临时文件
with tempfile.NamedTemporaryFile(
mode='w',
suffix=f'.{language}',
delete=False
) as f:
f.write(code)
temp_path = f.name
try:
# 2. Docker容器执行
result = subprocess.run(
[
"docker", "run",
"--rm",
"--network", "none", # 断网
"--memory", "256m", # 内存限制
"--cpus", "0.5", # CPU限制
"-v", f"{temp_path}:/code/{os.path.basename(temp_path)}",
self.image,
"python", f"/code/{os.path.basename(temp_path)}"
],
capture_output=True,
timeout=self.timeout
)
return {
"success": result.returncode == 0,
"output": result.stdout.decode(),
"error": result.stderr.decode()
}
except subprocess.TimeoutExpired:
return {
"success": False,
"output": "",
"error": "Execution timeout"
}
finally:
# 3. 清理临时文件
os.unlink(temp_path)
# 使用示例
@sandbox.execute
def execute_code(code: str) -> str:
"""安全执行用户代码"""
pass
```
### 4.5 Human in the Loop (人工审批)
```python
# python/app/security/approval.py
from enum import Enum
from dataclasses import dataclass
from typing import Optional
from datetime import datetime
import asyncio
class ApprovalStatus(Enum):
PENDING = "pending"
APPROVED = "approved"
REJECTED = "rejected"
@dataclass
class ApprovalRequest:
"""审批请求"""
request_id: str
tool_name: str
params: dict
user_id: str
reason: str
status: ApprovalStatus
created_at: datetime
reviewed_at: Optional[datetime]
reviewed_by: Optional[str]
class ApprovalService:
"""审批服务"""
def __init__(self, http_client):
self.client = http_client
self.pending: Dict[str, ApprovalRequest] = {}
async def request_approval(
self,
tool_name: str,
params: dict,
user_id: str,
reason: str
) -> str:
"""请求审批"""
request_id = generate_uuid()
approval_req = ApprovalRequest(
request_id=request_id,
tool_name=tool_name,
params=params,
user_id=user_id,
reason=reason,
status=ApprovalStatus.PENDING,
created_at=datetime.now(),
reviewed_at=None,
reviewed_by=None
)
self.pending[request_id] = approval_req
# 通知Go后端有新审批
await self.notify_go_service(approval_req)
return request_id
async def wait_for_approval(self, request_id: str, timeout: int = 300) -> bool:
"""等待审批结果"""
start = datetime.now()
while (datetime.now() - start).seconds < timeout:
if request_id in self.pending:
status = self.pending[request_id].status
if status == ApprovalStatus.APPROVED:
return True
elif status == ApprovalStatus.REJECTED:
return False
await asyncio.sleep(1)
raise TimeoutError("Approval request timeout")
```
### 4.6 全链路审计
```python
# python/app/security/audit.py
from datetime import datetime
from typing import Any, Dict
import json
class AuditLogger:
"""审计日志"""
def __init__(self, log_file: str = "audit.log"):
self.log_file = log_file
def log(
self,
action: str,
user_id: str,
agent_id: str,
details: Dict[str, Any],
result: str = "success"
):
"""记录审计日志"""
entry = {
"timestamp": datetime.now().isoformat(),
"action": action,
"user_id": user_id,
"agent_id": agent_id,
"details": details,
"result": result
}
# 写入日志文件
with open(self.log_file, 'a') as f:
f.write(json.dumps(entry) + '\n')
# 发送到Go后端
self.send_to_backend(entry)
def log_tool_execution(
self,
user_id: str,
tool_name: str,
params: Dict[str, Any],
approved: bool,
result: Any
):
"""记录工具执行"""
self.log(
action="tool_execution",
user_id=user_id,
agent_id="",
details={
"tool_name": tool_name,
"params": params,
"approved": approved,
"result_preview": str(result)[:100]
}
)
```
---
## 五、权限模型 (Go端)
### 5.1 用户角色
```go
// go/internal/model/user.go
package model
// 权限级别
type PermissionLevel int
const (
PermissionRead PermissionLevel = 1 // 只读
PermissionWrite PermissionLevel = 2 // 读写
PermissionExecute PermissionLevel = 3 // 可执行工具
PermissionAdmin PermissionLevel = 4 // 管理员
)
// 角色定义
type Role struct {
ID string `json:"id"`
Name string `json:"name"`
Permissions []PermissionLevel `json:"permissions"`
}
// 用户
type User struct {
ID string `json:"id"`
Username string `json:"username"`
RoleID string `json:"role_id"`
Role *Role `json:"role,omitempty"`
}
```
### 5.2 Agent定义
```go
// go/internal/model/agent.go
package model
type Agent struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
OwnerID string `json:"owner_id"`
// Agent能力配置
Capabilities []string `json:"capabilities"` // 可用工具列表
MemoryLimit int64 `json:"memory_limit"` // 内存限制
Timeout int `json:"timeout"` // 超时时间
// 安全配置
SecurityLevel SecurityLevel `json:"security_level"`
AllowDangerousTools bool `json:"allow_dangerous_tools"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"updated_at"`
}
```
---
## 六、部署架构
### 6.1 Docker Compose
```yaml
# docker-compose.yml
version: '3.8'
services:
# Go API 服务
go-api:
build: ./go
ports:
- "8080:8080"
environment:
- DATABASE_URL=postgres://user:pass@db:5432/agents
- PYTHON_SERVICE_URL=http://python-agent:8081
- JWT_SECRET=your-secret
depends_on:
- db
- python-agent
# Python Agent 服务
python-agent:
build: ./python
ports:
- "8081:8081"
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
volumes:
- ./python/app:/app
- /var/run/docker.sock:/var/run/docker.sock # 如果需要Docker沙盒
# 数据库
db:
image: postgres:15
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: agents
volumes:
- db-data:/var/lib/postgresql/data
# Redis (缓存/会话)
redis:
image: redis:7
volumes:
- redis-data:/data
# 向量数据库 (可选)
qdrant:
image: qdrant/qdrant
volumes:
- qdrant-data:/qdrant/storage
volumes:
db-data:
redis-data:
qdrant-data:
```
---
## 七、开发流程
### 7.1 请求流程图
```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ 用户 │────▶│ Go │────▶│ Python │────▶│ LLM │────▶│ 返回 │
│ 请求 │ │ 鉴权 │ │ Agent │ │ +Tools │ │ 结果 │
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
│ │
│ │
▼ ▼
┌─────────┐ ┌─────────┐
│ 检查 │ │ 权限 │
│ 权限 │ │ 检查 │
└─────────┘ └─────────┘
│
▼
┌─────────────────────┐
│ 工具安全等级判断 │
└─────────────────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Safe │ │ Review │ │ Danger │
│ 直接执行 │ │ 等待审批 │ │ 拒绝执行 │
└──────────┘ └──────────┘ └──────────┘
```
### 7.2 目录结构总览
```
X-Agents/
├── docs/
│ └── ARCHITECTURE.md # 本文档
│
├── go/ # Go 后端
│ ├── cmd/
│ ├── internal/
│ ├── pkg/
│ ├── go.mod
│ └── Dockerfile
│
├── python/ # Python AI 层
│ ├── app/
│ │ ├── api/
│ │ ├── agent/
│ │ ├── llm/
│ │ ├── rag/
│ │ └── security/
│ ├── requirements.txt
│ └── Dockerfile
│
├── web/ # 前端 (Vue)
│ ├── src/
│ └── package.json
│
├── docker-compose.yml # 容器编排
└── README.md
```
---
## 八、总结
### 架构核心原则
| 原则 | 实现方式 |
|------|----------|
| **分层治理** | Go负责业务/权限，Python负责AI逻辑 |
| **安全优先** | 工具分级+权限控制+人工审批+审计日志 |
| **通信简洁** | HTTP JSON API，后续可升级gRPC |
| **可扩展** | 模块化设计，支持多Agent/多Python服务 |
| **可观测** | 全链路日志+监控 |
### 安全特性
- [x] 工具白名单机制
- [x] 安全等级分级 (Safe/Review/Danger)
- [x] RBAC权限控制
- [x] Human in the Loop 人工审批
- [x] 沙盒执行环境 (Docker)
- [x] 全链路审计日志
---
*本文档将随项目开发持续更新*
Reference in New Issue View Git Blame Copy Permalink