pingtai_agent/format_police_agent/USAGE.md

格式警察 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}

{
  "content": "{name: 'test', value: 123,}",
  "use_ai": true
}

---

MCP 调用

{
  "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

---

返回结果

{
  "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

{
  "content": "{\"valid\": true, \"count\": 42}"
}

---

MCP 调用

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_json",
    "arguments": {
      "content": "{\"valid\": true}"
    }
  }
}

---

参数说明

参数	类型	必需	默认值	说明
content	string	✅	-	待校验的文本内容

---

返回结果（合法）

{
  "success": true,
  "result": {
    "valid": true,
    "message": "有效的 JSON 格式",
    "json_type": "dict",
    "preview": "{'valid': True, 'count': 42}"
  }
}

返回结果（非法）

{
  "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

{
  "content": "{\"a\":1,\"b\":{\"c\":2}}",
  "indent": 4
}

---

MCP 调用

{
  "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）

---

返回结果

{
  "success": true,
  "result": {
    "success": true,
    "formatted_json": {
      "a": 1,
      "b": {
        "c": 2
      }
    },
    "formatted_string": "{\n  \"a\": 1,\n  \"b\": {\n    \"c\": 2\n  }\n}"
  }
}

---

统一错误格式

成功：

{
  "success": true,
  "result": {}
}

失败：

{
  "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