API-AI-072：API 与 Rust Runtime 版本兼容性协议与拒绝策略 #186

New Issue

wangdl · 2026-06-10T21:03:52+08:00

wangdl commented

2026-06-10 21:03:52 +08:00

目标

定义 API 与 Rust Runtime 独立部署时的版本兼容协议，防止 Snapshot / Result / Prompt / Schema 版本不匹配导致错误落库。

需要覆盖

Runtime 启动时上报 capability manifest。
API 记录 Runtime 支持的 snapshotVersion。
API 记录 Runtime 支持的 outputSchemaVersion。
API 记录 Runtime 支持的 jobType。
Runtime 拉取 Job 时只拉取自己兼容的 job。
Runtime 提交不兼容 result 时 API 拒绝。
API 升级 Snapshot 后，旧 Runtime 不应消费新版本任务。

Capability Manifest 示例

{
  "runtimeVersion": "0.1.0",
  "supportedJobTypes": [
    "learning_state_analysis",
    "quiz_generation",
    "flashcard_generation"
  ],
  "supportedSnapshotVersions": ["ai_snapshot_v1"],
  "supportedOutputSchemaVersions": ["analysis_output_v1", "quiz_output_v1"],
  "supportedPromptVersions": ["learning_state_v1", "quiz_v1"]
}

验收标准

Runtime poll job 时提交 capability。
API 只返回 Runtime 兼容的 job。
Snapshot version 不兼容时不返回 job。
Result schemaVersion 不兼容时拒绝落库。
错误码明确：RUNTIME_VERSION_INCOMPATIBLE / SNAPSHOT_VERSION_UNSUPPORTED / RESULT_SCHEMA_UNSUPPORTED。
Admin 后续可查看 Runtime 版本。
提供测试。

## 目标定义 API 与 Rust Runtime 独立部署时的版本兼容协议，防止 Snapshot / Result / Prompt / Schema 版本不匹配导致错误落库。 ## 需要覆盖 1. Runtime 启动时上报 capability manifest。 2. API 记录 Runtime 支持的 snapshotVersion。 3. API 记录 Runtime 支持的 outputSchemaVersion。 4. API 记录 Runtime 支持的 jobType。 5. Runtime 拉取 Job 时只拉取自己兼容的 job。 6. Runtime 提交不兼容 result 时 API 拒绝。 7. API 升级 Snapshot 后，旧 Runtime 不应消费新版本任务。 ## Capability Manifest 示例 ```json { "runtimeVersion": "0.1.0", "supportedJobTypes": [ "learning_state_analysis", "quiz_generation", "flashcard_generation" ], "supportedSnapshotVersions": ["ai_snapshot_v1"], "supportedOutputSchemaVersions": ["analysis_output_v1", "quiz_output_v1"], "supportedPromptVersions": ["learning_state_v1", "quiz_v1"] } ``` ## 验收标准 1. Runtime poll job 时提交 capability。 2. API 只返回 Runtime 兼容的 job。 3. Snapshot version 不兼容时不返回 job。 4. Result schemaVersion 不兼容时拒绝落库。 5. 错误码明确：RUNTIME_VERSION_INCOMPATIBLE / SNAPSHOT_VERSION_UNSUPPORTED / RESULT_SCHEMA_UNSUPPORTED。 6. Admin 后续可查看 Runtime 版本。 7. 提供测试。

wangdl added this to the M-API-AI-RUNTIME：API AI Runtime 调度与落库 milestone 2026-06-10 21:03:52 +08:00

wangdl added the

labels 2026-06-10 21:03:52 +08:00

wangdl commented

2026-06-11 21:42:10 +08:00

完成证据

产物: src/modules/ai-runtime/internal/runtime-internal.service.ts (更新)
提交: 012e26b

能力:

pollJobs: Runtime 注册/更新 RuntimeInstance 表 (capabilities + lastHeartbeatAt)
submitResult: schemaVersion 必须匹配 job.outputSchemaVersion，不匹配返回 RESULT_SCHEMA_UNSUPPORTED
heartbeat: 首次调用设置 startedAt
pollJobs capabilities 过滤: outputSchemaVersion 前置 where + snapshotVersion 后置 join (已有)
错误码: RESULT_SCHEMA_UNSUPPORTED, RUNTIME_VERSION_INCOMPATIBLE

## 完成证据产物: src/modules/ai-runtime/internal/runtime-internal.service.ts (更新) 提交: 012e26b 能力: - pollJobs: Runtime 注册/更新 RuntimeInstance 表 (capabilities + lastHeartbeatAt) - submitResult: schemaVersion 必须匹配 job.outputSchemaVersion，不匹配返回 RESULT_SCHEMA_UNSUPPORTED - heartbeat: 首次调用设置 startedAt - pollJobs capabilities 过滤: outputSchemaVersion 前置 where + snapshotVersion 后置 join (已有) - 错误码: RESULT_SCHEMA_UNSUPPORTED, RUNTIME_VERSION_INCOMPATIBLE

wangdl closed this issue

2026-06-11 21:42:11 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#186