feat: 实现 AI-First 代理系统
核心功能: - AIAgent 模型：AI 代理身份管理 - AIOperationLog: AI 操作日志记录 - AITask: AI 异步任务系统 - AIWebhook: AI webhook 订阅 API 端点: - POST /api/agents/auth/ - AI 代理认证 - GET/POST /api/agents/ - 代理管理 - GET /api/agent-logs/ - 操作日志查询 - GET/POST /api/agent-tasks/ - 任务管理 - GET/POST /api/agent-webhooks/ - Webhook 管理 - POST /api/batch/ - 批量操作 预置 AI 代理: - content-moderator-ai: 内容审核 AI - content-generator-ai: 内容生成 AI - service-curator-ai: 服务推荐 AI - analytics-ai: 数据分析 AI - admin-ai: 管理员 AI 文档: - AI_AGENT.md: AI-First 设计文档 - init_agents.py: AI 代理初始化脚本 测试: - 认证系统测试通过 - JWT token 生成正常 - 权限系统工作正常
This commit is contained in:
maoshen
310
city-manual/AI_AGENT.md
Normal file
310
city-manual/AI_AGENT.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# 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 如何自动化操作。
|
||||
Reference in New Issue
Block a user