AI 交互接口规范
核心原则
所有与 AI 模型交互的接口必须采用异步轮询模式，严禁前端同步等待 AI 响应。
接口模式
POST /api/xxx/start → 立即返回 { genStage: 'xxx_generating' }
GET /api/xxx/status → 轮询返回 { genStage, result?, error? }
超时规范
| 接口类型 |
超时 |
说明 |
| POST 启动接口 |
10s |
仅做参数校验 + 投递异步任务 |
| GET 轮询接口 |
5s |
查询数据库状态，不涉及 AI |
| 前端整体等待上限 |
600s |
超时后提示用户重试 |
状态流转
plan_generating → plan_ready (Plan 生成完成)
→ plan_failed (Plan 生成失败)
outline_generating → outline_ready (大纲生成完成)
→ outline_failed (大纲生成失败)
generating_content → completed (内容生成完成)
→ failed (内容生成失败)
实现要点
后端
- POST 端点在
setImmediate 中执行 AI 调用，不 await
- AI 结果写入数据库对应字段（bookAnalysis / outlineJson）
- 完成后更新
genStage 为 xxx_ready
- 失败时更新
genStage 为 xxx_failed + errorMsg
前端
- POST 后立即进入
setInterval 轮询，间隔 3s
- 收到
xxx_ready 后停止轮询，渲染结果
- 收到
xxx_failed 后显示错误，允许重试
- 超过 600s 整体上限后提示超时
禁止事项
- 禁止在 POST 端点中
await 异步 AI 调用
- 禁止前端设置超过 10s 的 POST 超时
- 禁止在轮询回调中重新 POST 启动新任务
已有交互式接口对照
| 步骤 |
POST (启动) |
GET (轮询) |
完成标记 |
| Step 2 Plan |
POST /books/:id/interactive/plan |
GET /books/:id/interactive/plan |
plan_ready |
| Step 3 Outline |
POST /books/:id/interactive/outline |
GET /books/:id/interactive/outline |
outline_ready |
| Step 4 Content |
POST /books/:id/interactive/generate |
GET /books/:id/progress |
progress >= 100 |
