api-server/docs/ai-runtime-api-reference.md

AI Runtime 接入文档

面向 Runtime 开发者和 iOS/Admin 前端开发者的 API 参考。

---

1. 错误码枚举

1.1 Internal API 错误码（Runtime ↔ API）

错误码	HTTP	说明	retryable
JOB_NOT_FOUND	404	Job 不存在	false
JOB_NOT_ACTIVE	409	Job 状态不是 locked/running	false
JOB_ALREADY_LOCKED	409	已被其他 Runtime 锁定	true
SNAPSHOT_NOT_FOUND	404	快照不存在（已废弃：自动重建）	false
CREDENTIAL_NOT_FOUND	404	凭证不存在或已删除	false
CREDENTIAL_REQUIRED	400	user_deepseek_key 模式缺少 credentialId	false
RESULT_ALREADY_EXISTS	409	重复提交（幂等 key 冲突）	false
RESULT_SCHEMA_UNSUPPORTED	422	schema 版本不支持	false
INTERNAL_ERROR	500	服务器内部错误	true

1.2 User API 错误码（iOS / Admin → API）

错误码	HTTP	说明
AI_ANALYSIS_DISABLED	400	用户未开启 AI 分析
INVALID_JOB_TYPE	400	jobType 不在支持列表中
INVALID_TARGET_TYPE	400	quiz/flashcard 必须 targetType=knowledge_base
CREDENTIAL_REQUIRED	400	user_deepseek_key 模式需要绑定凭证
CREDENTIAL_NOT_FOUND	404	凭证不存在或无权访问
DAILY_JOB_LIMIT_EXCEEDED	400	超过每日 AI Job 数量上限
DAILY_TOKEN_BUDGET_EXCEEDED	400	超过每日 Token 预算上限
PLATFORM_CIRCUIT_OPEN	503	平台熔断器开启，拒绝新请求
PLATFORM_CIRCUIT_HALF_OPEN	503	熔断器半开，仅允许少量请求
PLATFORM_TOKEN_BUDGET_EXCEEDED	400	平台日 Token 预算耗尽
PLATFORM_COST_BUDGET_EXCEEDED	400	平台日成本预算耗尽

1.3 Runtime 上报的错误码

Runtime 通过 POST /internal/runtime/jobs/{jobId}/fail 上报的错误码：

错误码	说明	retryable
JOB_CANCELLED	用户取消 Job	false
JOB_TIMEOUT	Job 执行超时（默认 120s）	false
MODEL_TIMEOUT	DeepSeek API 超时/503/502/500	true
MODEL_RATE_LIMIT	DeepSeek 429 限流	true
MODEL_NETWORK_ERROR	网络连接失败	true
SNAPSHOT_FETCH_FAILED	快照拉取失败	true
INVALID_SNAPSHOT	快照版本不兼容	false
CREDENTIAL_RESOLVE_FAILED	凭证解析失败	false
UNSUPPORTED_JOB_TYPE	jobType 不支持	false
MODEL_RESPONSE_INVALID	模型返回无效 JSON	false
MODEL_JSON_PARSE_FAILED	模型输出 JSON 解析失败	false

---

2. 限流说明

2.1 用户级限流

通过 UserAiSettings 控制，默认值：

参数	默认值	说明
maxDailyAiJobs	20	每日 AI Job 创建上限
maxDailyTokenBudget	100,000	每日 Token 消耗上限

超出限制返回 DAILY_JOB_LIMIT_EXCEEDED 或 DAILY_TOKEN_BUDGET_EXCEEDED。

限流粒度：(userId, localDate, apiKeyMode)，platform_key 和 user_deepseek_key 独立计数。

2.2 平台级熔断

平台密钥（platform_key）模式启用的保护机制：

├── 日 Token 预算：10,000,000 tokens
├── 日成本预算：$500 (50000 cents)
├── 熔断阈值：连续 10 次失败 → open
├── 半开限制：最多 2 个活跃 platform_key Job
└── 恢复：单次成功 → closed（重置失败计数）

熔断状态流转：

closed ──[10次连续失败]──> open ──[手动半开]──> half_open ──[成功]──> closed
                         │                                    │
                         └───[超限]───<───────────────[超限]───┘

2.3 API 全局限流

通过 NestJS ThrottlerModule 控制，默认限制：

端点	限制	窗口
/ai/* 用户端点	60 次/分钟	60s
/internal/runtime/*	300 次/分钟	60s

超限返回 HTTP 429。

---

3. 变更日志

v1.1.0（2026-06）

新增：

• Heartbeat 响应新增 cancelRequested 字段（HTTP 200 替代 204）
• getSnapshot 自动重建过期/缺失快照（不再返回 SNAPSHOT_EXPIRED）
• submitFailure 支持 JOB_CANCELLED 错误码
• 用户 API：POST /ai/jobs 创建分析 Job（11 步流程含幂等、配额、熔断）
• 用户 API：GET/POST/PUT/DELETE /ai/model-credentials 凭证管理
• 用户 API：GET /ai/analyses, /ai/recommendations, /ai/weak-points 分析结果查询
• 用户 API：GET /ai/quizzes, /ai/flashcards 已发布内容查询
• 平台预算熔断：PlatformBudgetService 日 Token/成本限制 + 熔断器
• 结果落库：persistResult 支持 5 种 jobType（learning_state_analysis / weak_point_analysis / next_action_planning / quiz_generation / flashcard_generation）
• 候选转换：convertQuizCandidates / convertFlashcardCandidates 去重 + 正式记录创建
• Job 完成通知：notifyJobComplete 推送通知给用户

修复：

• getProfile 的 ?? {} 修复（之前 Promise 永远 truthy）
• HeartbeatResponse.cancel_requested: bool 客户端适配
• N+1 去重查询 → 批量预取（Quiz/Flashcard convertCandidates）
• persistResult / notifyJobComplete fire-and-forget 增加日志 + 计数器
• job-reaper take:500 上限 → 游标批处理循环
• checkAndReserve → checkQuota 重命名（澄清只读语义）
• testCredential 使用 ConfigService 获取 DeepSeek baseUrl
• Quota 测试拆分 mockSettingsFindUnique / mockUsageFindUnique

v1.0.0（2026-05）

初始版本：

• Internal API：Poll / Lock / Heartbeat / GetSnapshot / ResolveCredential / SubmitResult / SubmitFailure / SubmitInvocationLogs
• User API：Profile / Settings / Learning Profile CRUD
• 鉴权：InternalAuthGuard（x-internal-api-key）+ JWT（用户端点）
• 加密：CredentialEncryptionService（AES-256-GCM）
• 配额：UserAiQuotaService（checkQuota + incrementJobCount + recordTokenUsage）

---

4. 接入示例

4.1 Runtime 心跳 + 取消检测（v1.1）

POST /internal/runtime/jobs/{jobId}/heartbeat
Authorization: Bearer <RUNTIME_SERVICE_TOKEN>
x-runtime-instance-id: runtime-001

响应 200：

{
  "jobId": "job-abc123",
  "lockUntil": 1700000000123,
  "cancelRequested": false
}

cancelRequested=true 时，Runtime 应在下一个 I/O 检查点中止执行并提交 JOB_CANCELLED fail。

4.2 前端创建分析 Job

POST /ai/jobs
Authorization: Bearer <USER_JWT>

{
  "jobType": "quiz_generation",
  "targetType": "knowledge_base",
  "targetId": "kb-001",
  "apiKeyMode": "platform_key",
  "idempotencyKey": "client-uuid-xxx",
  "questionCount": 10
}

幂等：相同 idempotencyKey 重复请求返回已有 Job ID（不重复创建）。

---

5. 相关资源

• Internal API 通信协议
• AI Runtime 架构
• Job 状态机
• 数据权限与隐私
• 用户 AI API 文档