EasyVista高级工具 - JSON-RPC封装器
一个高级、可投入生产的JSON-RPC 2.0封装工具，用于EasyVista REST API。此服务提供了一个强大、可扩展且易于使用的接口，用于与EasyVista进行交互，旨在与LLM代理（如Open-WebUI）和其他外部系统集成。
特点/功能
- 异步且高性能使用FastAPI构建
httpx用于高性能、非阻塞I/O。 - 强大的错误处理包括自动重试功能，采用指数退避策略，并将API错误转换为标准的JSON-RPC错误响应。
- 安全的使用API密钥身份验证保护服务。
- 丰富的工具集提供了一套全面的工具，用于管理工单和生成报告。
- 集装箱化使用Docker和Docker Compose实现完全容器化，便于部署和扩展。
- 包含模拟API随附一个内置的模拟API用于测试和开发，使您能够在没有实际EasyVista实例的情况下运行服务。
建筑
该项目采用了一种简洁、分层的架构，实现了关注点的分离：
- API 层（
app/api）所有传入请求的入口点，使用FastAPI构建。 - 服务层 (
app/services）包含与EasyVista API交互的业务逻辑。 - 数据模型层 (
app/models）使用 Pydantic 定义应用程序中使用的数据结构。 - 核心配置（
app/core)管理应用程序级别的设置和环境变量。
入门指南/开始使用
先决条件
- Docker
- Docker Compose
安装
- 克隆仓库：
git clone git@github.com:antuelle78/easyvista_advanced.git
cd easyvista_advanced- 配置环境：
创建一个 .env 在项目根目录下创建文件并添加以下变量。对于本地测试，默认值将与随附的模拟API一起正常工作。
# The URL of the EasyVista API (or the mock API)
EASYVISTA_URL=http://mock_api:8085
# The API key for the EasyVista API
EASYVISTA_API_KEY=your_api_key
# The account ID for the EasyVista API
EASYVISTA_ACCOUNT_ID=your_account_id
# The API key to secure this service
EASYVISTA_TOOL_API_KEY=a-very-secret-api-key- 构建并运行服务：
docker compose up --build -d这将启动 easyvista_tool 服务（可在 http://localhost:8004）以及 mock_api 服务（可在 http://localhost:8085）。
使用方法
所有工具均通过一个单一的JSON-RPC端点进行访问： http://localhost:8004/api/v1/mcp。
您必须在其中包含您的API密钥 X-API-KEY 所有请求的头部信息。
示例请求（list_tickets):
curl -X POST http://localhost:8004/api/v1/mcp \
-H "Content-Type: application/json" \
-H "X-API-KEY: a-very-secret-api-key" \
-d '{'\
"jsonrpc": "2.0",
"method": "list_tickets",
"params": {"status": "Open"},
"id": 1
}'生产环境配置（连接到真实的EasyVista实例）
要将服务连接到您实际的EasyVista实例，您需要更新 .env 附上您的生产凭据文件：
EASYVISTA_URL请将此更改为您的组织的EasyVista API终端节点。
EASYVISTA_URL=https://your-company.easyvista.comEASYVISTA_API_KEY使用从您的EasyVista帐户生成的有效API密钥（Bearer Token）。
EASYVISTA_API_KEY=your-real-easyvista-api-keyEASYVISTA_ACCOUNT_ID将此设置为您在EasyVista的账户ID。
EASYVISTA_ACCOUNT_ID=your-account-id更新后 .env 文件，重启服务：
docker compose up -d --build对于生产环境的部署，你也可以删除或注释掉 mock_api 来自（某处的）服务 docker-compose.yml 将其存档，因为它将不再需要。
Kubernetes 部署（或“Kubernetes 部署对象”）
这个项目包含一个用于部署的Kubernetes清单文件 easyvista_tool 为单节点 k3s 集群提供服务。
先决条件
- 一个正在运行的 Kubernetes 集群（例如，k3s、Minikube）。
kubectl配置为连接到您的集群。
部署步骤
- 编码你的秘密：
这个 kubernetes_manifest.yaml 文件要求您的密钥需进行Base64编码。请使用以下命令对您的凭据进行编码：
echo -n 'your-real-easyvista-api-key' | base64
echo -n 'your-account-id' | base64
echo -n 'a-very-secret-api-key' | base64- 更新清单：
打开 kubernetes_manifest.yaml 并替换其中的占位符值 Secret 使用Base64编码的凭据作为资源。您还必须更新 EASYVISTA_URL 在……里 ConfigMap 指向您的生产环境EasyVista实例。
- 应用清单（或：执行清单）：
kubectl apply -f kubernetes_manifest.yaml- 访问服务：
该服务将暴露在端口上 30087 在您的 Kubernetes 节点上。您可以访问它于 http://:30087.
API 参考
以下工具可供使用：
| 方法 | 描述 | 参数 |
|---|---|---|
create_ticket 创建一个新工单。 | title， description， category， priority， support_team （可选）， assigned_to （可选） | |
assign_ticket 将工单分配给支持人员。 | rfc_number， assigned_to | |
get_ticket | 通过RFC编号检索单个工单。 | rfc_number |
get_ticket_history | 获取票务的状态历史记录。 | rfc_number |
list_tickets | 列出票据，可选择过滤。 | status， priority， group_id， assigned_to， limit， offset |
get_tickets_by_group | 获取特定组的票据。 | group_id |
get_tickets_by_status | 获取具有特定状态的票据。 | status |
get_tickets_by_priority | 获取具有特定优先级的工单。 | priority |
generate_report 生成工单报告。 | report_type (summary， csv， html)， filters (status， priority， group_id， assigned_to) | |
get_resolution_metrics | 按团队检索平均解决时间。 | （无） |
运行测试
该项目包含一整套单元测试。要运行这些测试，请执行以下命令：
docker compose exec easyvista_tool pytest这将在服务容器内部运行测试，确保测试环境的一致性。
做出贡献
欢迎贡献！请随时提交拉取请求。
许可证
这个项目遵循MIT许可证授权——详见 许可证 详情请参阅文件。