pingtai_agent/format_police_agent/README.md

# 格式警察 Agent (Format Police Agent)

🚔 **只做一件事**：检查输出是否符合 JSON 格式，如果不符合则补全格式化 JSON 输出。

## 功能特性

- ✅ **JSON 验证**：检查内容是否为有效 JSON
- 🔧 **自动修复**：尝试修复常见的 JSON 格式问题
- 🤖 **AI 辅助**：无法自动修复时使用 AI 转换
- 📦 **格式化输出**：美化 JSON 输出

## 快速开始

### 1. 本地运行

```bash
# 安装依赖
pip install -r requirements.txt

# 启动服务
python run_api_server.py
```

### 2. Docker 运行

```bash
# 构建镜像
docker build -t format-police-agent:latest .

# 运行容器
docker run -p 8000:8000 -e OPENAI_API_KEY=your_key format-police-agent:latest
```

## API 端点

### 健康检查

```bash
curl http://localhost:8000/health
```

### MCP 端点

| 端点 | 方法 | 说明 |
|------|------|------|
| `/mcp` | POST | MCP HTTP 端点 |
| `/mcp/sse` | GET/POST | MCP SSE 端点 |

### REST API

| 端点 | 方法 | 说明 | 需要 API Key |
|------|------|------|-------------|
| `/api/v1/check` | POST | 检查并修复 JSON | 是（使用 AI 时）|
| `/api/v1/validate` | POST | 仅验证 JSON | 否 |
| `/api/v1/format` | POST | 格式化 JSON | 否 |

## MCP 工具

### check_and_fix_json

检查并修复 JSON 格式。

```json
{
  "name": "check_and_fix_json",
  "arguments": {
    "content": "需要检查的内容",
    "use_ai": true
  }
}
```

**参数：**
- `content` (必需): 需要检查和修复的内容
- `use_ai` (可选): 是否使用 AI 辅助修复，默认 `true`

### validate_json

仅验证 JSON 格式是否有效。

```json
{
  "name": "validate_json",
  "arguments": {
    "content": "需要验证的内容"
  }
}
```

### format_json

格式化已有效的 JSON。

```json
{
  "name": "format_json",
  "arguments": {
    "content": "{\"a\":1}",
    "indent": 2
  }
}
```

## 使用示例

### 1. 检查并修复 JSON

```bash
curl -X POST http://localhost:8000/api/v1/check \
  -H "Content-Type: application/json" \
  -H "api-key: your_api_key" \
  -d '{"content": "{name: \"test\", value: 123}"}'
```

响应：
```json
{
  "success": true,
  "result": {
    "success": true,
    "is_original_valid": false,
    "message": "已自动修复 JSON 格式问题",
    "formatted_json": {
      "name": "test",
      "value": 123
    }
  }
}
```

### 2. 验证 JSON（无需 API Key）

```bash
curl -X POST http://localhost:8000/api/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"content": "{\"valid\": true}"}'
```

### 3. MCP 调用

```bash
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "api-key: your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "check_and_fix_json",
      "arguments": {
        "content": "这不是JSON，但包含信息：名字是张三，年龄25"
      }
    }
  }'
```

## 自动修复能力

格式警察可以自动修复以下问题：

1. **单引号** → 双引号
2. **末尾多余逗号** → 移除
3. **未加引号的值** → 添加引号
4. **Markdown 代码块** → 提取 JSON
5. **BOM 字符** → 移除

无法自动修复时，会使用 AI 尝试转换。

## 环境变量

| 变量 | 必需 | 说明 | 默认值 |
|------|------|------|--------|
| OPENAI_API_KEY | 使用 AI 时 | OpenAI API Key | - |
| OPENAI_BASE_URL | 否 | LLM API 地址 | LiteLLM Gateway |
| MODEL_NAME | 否 | 模型名称 | taiji/gpt-4o-mini |
| API_HOST | 否 | 监听地址 | 0.0.0.0 |
| API_PORT | 否 | 监听端口 | 8000 |

## 注册到 Agent Manager

在 `k8s_manager.py` 中添加：

```python
# TEMPLATE_PORTS
"format_police": 8000,

# image_map
"format_police": "agnettaiji.azurecr.io/ai-agents/format-police-agent:latest",
```

在 `app.py` 的 `valid_templates` 中添加 `"format_police"`。

## 项目结构

```
format_police_agent/
├── Dockerfile
├── requirements.txt
├── run_api_server.py
├── README.md
└── src/
    ├── __init__.py
    └── server/
        ├── __init__.py
        ├── api_server.py   # FastAPI + MCP HTTP
        └── mcp_server.py   # MCP 工具定义
```

## License

MIT