chengshishouce/city-manual/AI_AGENT.md

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

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

📝 内容生成 AI

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

🏪 服务推荐 AI

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

📊 数据分析 AI

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

🔍 搜索优化 AI

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

AI 专用 API 端点

AI 身份认证

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 批量操作

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 任务状态查询

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 回调

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

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

AI 操作日志

# 数据库模型
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 自动运营流程

# 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

配置示例

# 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 如何自动化操作。