diff --git a/docs/ai-runtime-internal-api-protocol.md b/docs/ai-runtime-internal-api-protocol.md index ea0774a..31ad0cb 100644 --- a/docs/ai-runtime-internal-api-protocol.md +++ b/docs/ai-runtime-internal-api-protocol.md @@ -45,8 +45,7 @@ x-runtime-instance-id: runtime-001 |--------|------|------|-----------| | `JOB_NOT_FOUND` | 404 | Job 不存在 | false | | `JOB_ALREADY_LOCKED` | 409 | 已被其他 Runtime 锁定 | true | -| `SNAPSHOT_EXPIRED` | 410 | 快照已过期 | true | -| `SNAPSHOT_NOT_FOUND` | 404 | 快照不存在 | false | +| `SNAPSHOT_NOT_FOUND` | 404 | 快照不存在(已废弃:getSnapshot 自动重建) | false | | `CREDENTIAL_NOT_FOUND` | 404 | 凭证不存在 | false | | `CREDENTIAL_INVALID` | 422 | 凭证无效 | false | | `RESULT_ALREADY_EXISTS` | 409 | 重复提交 | false | @@ -125,7 +124,9 @@ Runtime 锁定一个 job,获取执行权。 POST /internal/runtime/jobs/{jobId}/heartbeat ``` -Runtime 延长 lock 有效期。 +Runtime 延长 lock 有效期。首次调用完成 locked→running 转换并设置 startedAt;后续调用仅延长 lockUntil。 + +同时返回 `cancelRequested` 标志 — 若用户已请求取消,Runtime 应在下一个检查点中止执行。 **请求**: ```json @@ -134,7 +135,20 @@ Runtime 延长 lock 有效期。 } ``` -**响应 204**:空 body,仅延长 `lockUntil`。 +**响应 200**: +```json +{ + "jobId": "job-abc123", + "lockUntil": 1700000000123, + "cancelRequested": false +} +``` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `jobId` | string | Job ID | +| `lockUntil` | number | 锁过期时间(ms epoch) | +| `cancelRequested` | boolean | 用户是否已请求取消。true 时 Runtime 应提交 JOB_CANCELLED 并中止 | ### 4.4 Get Snapshot @@ -144,6 +158,8 @@ GET /internal/runtime/jobs/{jobId}/snapshot Runtime 获取 job 关联的 LearningAnalysisSnapshot。 +若 job 无关联快照、快照不存在、或快照 sourceDataVersion 过旧 / 已过期,API 自动调用 `SnapshotBuilder.buildSnapshot` 重建新快照并绑定到 job。Runtime 无需处理快照过期逻辑。 + **响应 200**: ```json { @@ -163,8 +179,7 @@ Runtime 获取 job 关联的 LearningAnalysisSnapshot。 ``` **错误**: -- `404 SNAPSHOT_NOT_FOUND` — 快照不存在 -- `410 SNAPSHOT_EXPIRED` — 快照已过期,Runtime 应提交 retryable fail +- `404 JOB_NOT_FOUND` — Job 不存在 ### 4.5 Resolve Credential @@ -265,8 +280,9 @@ Runtime 提交执行失败的原因。 ``` **处理规则**: +- `errorCode=JOB_CANCELLED`:job 立即标记为 `cancelled`(无论 retryable 值) - `retryable=true` 且 `retryCount < maxRetryCount`:job 回到 `pending` -- `retryable=false` 或达到 maxRetryCount:job 变为 `failed` +- `retryable=false` 或达到 maxRetryCount:job 变为 `failed`,触发通知 - `rawError` 中不得包含 apiKey **响应 200**:acknowledged