# AI Agent 设计文档

> 城市手册是一个 **AI-First** 的应用，所有功能都可以由 AI 机器人自动操作

## 设计原则

### 1. 机器可读的 API

- ✅ RESTful 设计，资源导向
- ✅ 统一的 JSON 响应格式
- ✅ 标准化的错误码和错误信息
- ✅ 完整的 OpenAPI/Swagger 文档
- ✅ HATEOAS 链接（可选）

### 2. 自动化的认证流程

- ✅ JWT Token，无状态认证
- ✅ Token 自动刷新机制
- ✅ Service Account 支持（AI 专用账号）
- ✅ API Key 支持（长期有效）

### 3. 结构化的日志系统

- ✅ 所有操作记录到数据库
- ✅ 区分人类用户和 AI 代理
- ✅ 操作审计追踪
- ✅ 机器可读的日志格式

### 4. AI 友好的错误处理

- ✅ 明确的错误码
- ✅ 详细的错误描述
- ✅ 建议的修复方案
- ✅ 多语言支持（可选）

### 5. 批量操作支持

- ✅ 批量创建/更新/删除
- ✅ 异步任务支持
- ✅ 任务状态查询
- ✅ 操作结果回调

## AI 代理类型

### 🤖 内容审核 AI

```python
# AI 审核员自动审核用户提交的内容
POST /api/articles/{id}/review/
{
  "agent_id": "content-moderator-ai",
  "action": "approve" | "reject",
  "reason": "内容符合社区规范",
  "confidence": 0.95
}
```

### 📝 内容生成 AI

```python
# AI 作者自动生成城市介绍文章
POST /api/articles/
{
  "agent_id": "content-generator-ai",
  "title": "北京市旅游指南",
  "region": 1,
  "content": "...",
  "auto_generated": true
}
```

### 🏪 服务推荐 AI

```python
# AI 推荐官自动添加特色服务
POST /api/services/
{
  "agent_id": "service-curator-ai",
  "name": "故宫博物院",
  "region": 1,
  "category": "旅游",
  "description": "...",
  "auto_generated": true
}
```

### 📊 数据分析 AI

```python
# AI 分析师生成统计报告
GET /api/analytics/summary?agent=analytics-ai
```

### 🔍 搜索优化 AI

```python
# AI 优化搜索索引
POST /api/search/optimize/
{
  "agent_id": "search-optimizer-ai",
  "scope": "all" | "regions" | "articles" | "services"
}
```

## AI 专用 API 端点

### AI 身份认证

```http
POST /api/agents/auth/
Content-Type: application/json

{
  "agent_id": "content-moderator-ai",
  "agent_secret": "xxx",
  "capabilities": ["review", "approve", "reject"]
}

Response:
{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 3600,
  "agent_info": {
    "id": "content-moderator-ai",
    "name": "内容审核 AI",
    "permissions": ["review", "approve", "reject"]
  }
}
```

### AI 批量操作

```http
POST /api/batch/
Content-Type: application/json
Authorization: Bearer {agent_token}

{
  "operations": [
    {
      "method": "POST",
      "path": "/api/articles/",
      "body": {"title": "...", "content": "..."}
    },
    {
      "method": "PUT",
      "path": "/api/articles/1/",
      "body": {"title": "..."}
    },
    {
      "method": "DELETE",
      "path": "/api/articles/2/"
    }
  ]
}

Response:
{
  "task_id": "batch-123",
  "status": "processing",
  "results": [...]
}
```

### AI 任务状态查询

```http
GET /api/tasks/{task_id}/
Authorization: Bearer {agent_token}

Response:
{
  "id": "batch-123",
  "type": "batch_operation",
  "status": "completed" | "processing" | "failed",
  "progress": 100,
  "created_at": "2026-04-12T11:00:00Z",
  "completed_at": "2026-04-12T11:05:00Z",
  "result": {...},
  "error": null
}
```

### AI Webhook 回调

```http
POST /api/webhooks/
Content-Type: application/json
Authorization: Bearer {agent_token}

{
  "event": "article.created",
  "url": "https://ai-agent.example.com/webhook",
  "secret": "xxx"
}
```

## AI 操作日志

```python
# 数据库模型
class AIOperationLog(models.Model):
    agent_id = models.CharField(max_length=100)  # AI 代理 ID
    action = models.CharField(max_length=50)     # 操作类型
    resource_type = models.CharField(max_length=50)  # 资源类型
    resource_id = models.IntegerField()          # 资源 ID
    status = models.CharField(max_length=20)     # success/failed
    confidence = models.FloatField()             # AI 置信度
    reasoning = models.TextField()               # AI 推理过程
    created_at = models.DateTimeField(auto_now_add=True)
```

## AI 权限系统

| 权限 | 说明 | 适用 AI |
|------|------|--------|
| `ai:read` | 读取数据 | 所有 AI |
| `ai:write` | 创建/更新数据 | 内容生成 AI、服务推荐 AI |
| `ai:review` | 审核内容 | 内容审核 AI |
| `ai:delete` | 删除数据 | 管理员 AI |
| `ai:batch` | 批量操作 | 所有 AI |
| `ai:analytics` | 访问分析数据 | 数据分析 AI |

## 最佳实践

### 1. AI 应该

- ✅ 使用专用的 AI 账号（Service Account）
- ✅ 记录所有操作的 `agent_id`
- ✅ 提供操作的置信度
- ✅ 提供操作的推理过程
- ✅ 支持人工复核
- ✅ 遵守速率限制

### 2. AI 不应该

- ❌ 使用人类用户的账号
- ❌ 隐藏 AI 身份
- ❌ 绕过审核流程
- ❌ 无限制批量操作
- ❌ 忽略错误处理

## 示例：AI 自动运营流程

```python
# 1. AI 内容生成器创建文章
POST /api/articles/
{
  "agent_id": "content-generator-ai",
  "title": "成都美食攻略",
  "region": 11,
  "content": "...",
  "auto_generated": true
}

# 2. AI 审核器自动审核
POST /api/articles/{id}/review/
{
  "agent_id": "content-moderator-ai",
  "action": "approve",
  "confidence": 0.98,
  "reasoning": "内容质量高，无明显问题"
}

# 3. AI 推荐器添加到首页
POST /api/featured/
{
  "agent_id": "recommendation-ai",
  "article_id": 123,
  "reason": "热门文章，用户关注度高"
}

# 4. AI 分析器生成报告
GET /api/analytics/daily?agent=analytics-ai
```

## 配置示例

```python
# settings.py
AI_AGENTS = {
    'content-moderator-ai': {
        'name': '内容审核 AI',
        'secret': 'xxx',
        'permissions': ['review', 'approve', 'reject'],
        'rate_limit': 1000,  # 每小时请求数
    },
    'content-generator-ai': {
        'name': '内容生成 AI',
        'secret': 'xxx',
        'permissions': ['write'],
        'rate_limit': 100,
    },
    # ...
}
```

## 未来扩展

- [ ] 自然语言查询接口
- [ ] AI 之间的协作协议
- [ ] 多 AI 投票决策机制
- [ ] AI 操作可视化面板
- [ ] AI 性能评估系统
- [ ] AI 训练数据导出

---

**设计理念：** 城市手册不仅是给人用的，更是给 AI 用的。每一个 API、每一个功能、每一个流程，都要考虑 AI 如何自动化操作。