API-AI-001：API 与 Rust Runtime 内部通信协议设计 #162

New Issue

wangdl · 2026-06-10T21:01:46+08:00

wangdl commented

2026-06-10 21:01:46 +08:00

目标

定义 API 与 Rust Heavy Runtime 的内部通信协议，包括 Job 拉取、Job 锁定、Snapshot 获取、模型凭证解析、结果提交、失败提交、调用日志提交。

DTO 要求

必须定义：

RuntimePollJobsRequestDto
RuntimePollJobsResponseDto
RuntimeLockJobRequestDto
RuntimeLockJobResponseDto
RuntimeHeartbeatRequestDto
RuntimeSnapshotResponseDto
RuntimeResolveCredentialRequestDto
RuntimeResolveCredentialResponseDto
RuntimeSubmitResultRequestDto
RuntimeSubmitFailureRequestDto
RuntimeInvocationLogDto

安全要求

所有 internal/runtime 接口必须使用 service token。
service token 不可用于普通用户 API。
Runtime 不可通过 internal 接口访问非当前 job 所需数据。
用户 key 不可写入日志。
Runtime result 必须带 jobId、schemaVersion、runtimeInstanceId。

不做范围

不做公网 API。
不接入 iOS。
不接入 Admin 前端页面。
不允许 Runtime 通过这些接口修改普通业务数据。

验收标准

输出完整通信协议文档。
所有 internal 接口有 DTO 定义。
所有 internal 接口有鉴权设计。
所有失败返回包含 errorCode / message。
Runtime result 支持结构化 payload。
Runtime failure 支持 retryable 标记。
Credential resolve 接口明确不记录明文 key。
接口命名、字段命名与 Runtime 项目可直接对齐。

## 目标定义 API 与 Rust Heavy Runtime 的内部通信协议，包括 Job 拉取、Job 锁定、Snapshot 获取、模型凭证解析、结果提交、失败提交、调用日志提交。 ## 推荐内部接口 ``` POST /internal/runtime/jobs/poll POST /internal/runtime/jobs/{jobId}/lock POST /internal/runtime/jobs/{jobId}/heartbeat GET /internal/runtime/jobs/{jobId}/snapshot POST /internal/runtime/model-credentials/resolve POST /internal/runtime/jobs/{jobId}/result POST /internal/runtime/jobs/{jobId}/fail POST /internal/runtime/invocation-logs GET /internal/runtime/health ``` ## DTO 要求必须定义： - RuntimePollJobsRequestDto - RuntimePollJobsResponseDto - RuntimeLockJobRequestDto - RuntimeLockJobResponseDto - RuntimeHeartbeatRequestDto - RuntimeSnapshotResponseDto - RuntimeResolveCredentialRequestDto - RuntimeResolveCredentialResponseDto - RuntimeSubmitResultRequestDto - RuntimeSubmitFailureRequestDto - RuntimeInvocationLogDto ## 安全要求 1. 所有 internal/runtime 接口必须使用 service token。 2. service token 不可用于普通用户 API。 3. Runtime 不可通过 internal 接口访问非当前 job 所需数据。 4. 用户 key 不可写入日志。 5. Runtime result 必须带 jobId、schemaVersion、runtimeInstanceId。 ## 不做范围 1. 不做公网 API。 2. 不接入 iOS。 3. 不接入 Admin 前端页面。 4. 不允许 Runtime 通过这些接口修改普通业务数据。 ## 验收标准 1. 输出完整通信协议文档。 2. 所有 internal 接口有 DTO 定义。 3. 所有 internal 接口有鉴权设计。 4. 所有失败返回包含 errorCode / message。 5. Runtime result 支持结构化 payload。 6. Runtime failure 支持 retryable 标记。 7. Credential resolve 接口明确不记录明文 key。 8. 接口命名、字段命名与 Runtime 项目可直接对齐。

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

wangdl added the

labels 2026-06-10 21:01:46 +08:00

Sign in to join this conversation.