forked from chenchen/pingtai_agent
318 lines
5.3 KiB
Markdown
318 lines
5.3 KiB
Markdown
# 格式警察 Agent
|
||
|
||
---
|
||
|
||
本 Agent 提供基于 **智能解析** 的 JSON 格式校验与修复能力，通过 **HTTP API** 与 **MCP（Model Context Protocol）** 对外提供服务。
|
||
|
||
核心能力：
|
||
|
||
- **格式校验**：符合 RFC 8259 标准的 JSON 语法检测
|
||
- **智能修复**：基于规则引擎与 LLM 的多级修复策略
|
||
- **格式美化**：可配置缩进的结构化输出
|
||
|
||
---
|
||
|
||
## 功能概览
|
||
|
||
提供 JSON 文本的 **语法验证、智能修复、格式化输出** 能力，返回结构化处理结果。
|
||
|
||
支持能力：
|
||
|
||
- JSON Schema 合规性校验
|
||
- 常见语法错误自动修复
|
||
- LLM 辅助的非结构化文本转换
|
||
- 可配置的格式化输出
|
||
|
||
---
|
||
|
||
## 1⃣ check_and_fix_json — 智能校验与修复
|
||
|
||
### 功能说明
|
||
|
||
对输入内容执行 **多级修复策略**：优先通过规则引擎修复常见语法问题，失败时启用 LLM 进行语义转换，确保输出符合 JSON 规范。
|
||
|
||
---
|
||
|
||
### REST API 调用
|
||
|
||
```
|
||
POST /api/v1/check
|
||
Content-Type: application/json
|
||
api-key: {your-api-key}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"content": "{name: 'test', value: 123,}",
|
||
"use_ai": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### MCP 调用
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "check_and_fix_json",
|
||
"arguments": {
|
||
"content": "{name: 'test', value: 123,}",
|
||
"use_ai": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| content | string | ✅ | - | 待校验或修复的文本内容 |
|
||
| use_ai | boolean | ❌ | true | 是否启用 LLM 辅助修复 |
|
||
|
||
---
|
||
|
||
### 修复策略
|
||
|
||
| 阶段 | 策略 | 说明 |
|
||
| --- | --- | --- |
|
||
| L1 | 直接解析 | 验证是否为合法 JSON |
|
||
| L2 | 模式提取 | 从代码块 / 嵌套文本中提取 JSON |
|
||
| L3 | 规则修复 | 修复引号、逗号等常见语法问题 |
|
||
| L4 | LLM 转换 | 调用大模型将非结构化文本转为 JSON |
|
||
|
||
---
|
||
|
||
### 返回结果
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": {
|
||
"success": true,
|
||
"is_original_valid": false,
|
||
"message": "已自动修复 JSON 格式问题",
|
||
"formatted_json": {
|
||
"name": "test",
|
||
"value": 123
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 返回字段说明
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| success | boolean | 处理是否成功 |
|
||
| is_original_valid | boolean | 原始输入是否为合法 JSON |
|
||
| message | string | 处理结果描述 |
|
||
| formatted_json | object/array | 修复后的 JSON 对象 |
|
||
|
||
---
|
||
|
||
## 2️⃣ validate_json — 格式校验
|
||
|
||
### 功能说明
|
||
|
||
执行 **只读校验**，验证输入是否符合 JSON 语法规范，返回详细的错误定位信息，不进行任何修改。
|
||
|
||
---
|
||
|
||
### REST API 调用
|
||
|
||
```
|
||
POST /api/v1/validate
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"content": "{\"valid\": true, \"count\": 42}"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### MCP 调用
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "validate_json",
|
||
"arguments": {
|
||
"content": "{\"valid\": true}"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| content | string | ✅ | - | 待校验的文本内容 |
|
||
|
||
---
|
||
|
||
### 返回结果（合法）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": {
|
||
"valid": true,
|
||
"message": "有效的 JSON 格式",
|
||
"json_type": "dict",
|
||
"preview": "{'valid': True, 'count': 42}"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 返回结果（非法）
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": {
|
||
"valid": false,
|
||
"message": "无效的 JSON 格式",
|
||
"error_detail": "位置 1: Expecting property name enclosed in double quotes",
|
||
"suggestion": "可以使用 check_and_fix_json 工具尝试修复"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 3️⃣ format_json — 格式美化
|
||
|
||
### 功能说明
|
||
|
||
对合法 JSON 执行 **结构化美化输出**，支持自定义缩进层级，便于阅读与调试。
|
||
|
||
---
|
||
|
||
### REST API 调用
|
||
|
||
```
|
||
POST /api/v1/format
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"content": "{\"a\":1,\"b\":{\"c\":2}}",
|
||
"indent": 4
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### MCP 调用
|
||
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "format_json",
|
||
"arguments": {
|
||
"content": "{\"a\":1,\"b\":{\"c\":2}}",
|
||
"indent": 2
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 参数说明
|
||
|
||
| 参数 | 类型 | 必需 | 默认值 | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| content | string | ✅ | - | 合法的 JSON 字符串 |
|
||
| indent | integer | ❌ | 2 | 缩进空格数（1-8） |
|
||
|
||
---
|
||
|
||
### 返回结果
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": {
|
||
"success": true,
|
||
"formatted_json": {
|
||
"a": 1,
|
||
"b": {
|
||
"c": 2
|
||
}
|
||
},
|
||
"formatted_string": "{\n \"a\": 1,\n \"b\": {\n \"c\": 2\n }\n}"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 统一错误格式
|
||
|
||
成功：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"result": {}
|
||
}
|
||
```
|
||
|
||
失败：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"error": "错误描述"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 服务端点
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
| --- | --- | --- |
|
||
| / | GET | 服务状态 |
|
||
| /health | GET | 健康检查 |
|
||
| /mcp | POST | MCP JSON-RPC |
|
||
| /mcp/sse | GET/POST | MCP SSE 流式 |
|
||
| /api/v1/check | POST | 智能校验与修复 |
|
||
| /api/v1/validate | POST | 格式校验 |
|
||
| /api/v1/format | POST | 格式美化 |
|
||
|
||
---
|
||
|
||
## 部署信息
|
||
|
||
| 配置项 | 值 |
|
||
| --- | --- |
|
||
| 镜像地址 | agnettaiji.azurecr.io/ai-agents/format-police-agent:latest |
|
||
| 服务端口 | 8000 |
|
||
| 健康检查 | /health |
|
||
|
||
|