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

Sign in to join this conversation.