Dữ liệu gửi và vận chuyển

Vỏ bọc

interface PayloadEnvelope {
  schema_version: 1
  account_id: string
  project_id: string
  resource: string
  resource_id: string
  source: PayloadSource
  references: ArtifactRef[]
  payload: JsonObject
}

account_id và project_id đến từ dự án đã kiểm tra. Chúng định tuyến và cung cấp ngữ cảnh cho dữ liệu gửi; không phải thông tin xác thực và không cấp quyền truy cập. resource là trụ cột và kiểu, chẳng hạn vision.prd, còn resource_id là ID hiện vật hoặc sự kiện.

Với hiện vật Markdown, payload là { metadata, body }. Dữ liệu Record và Drift Event là vỏ bọc JSON đã kiểm tra của chúng. references là các tham chiếu tường minh được suy ra từ đầu vào đã kiểm tra.

Nguồn gốc dữ liệu

PayloadSource.kind nhận một trong các giá trị:

markdown — yêu cầu path tương đối an toàn
json — yêu cầu path tương đối an toàn
integration — yêu cầu integration và external_id

Hiện vật đã phân tích suy ra markdown hoặc json từ đường dẫn. Record trực tiếp suy ra nguồn tích hợp của nó. Drift Event trực tiếp không có trường nguồn nên bên gọi phải cung cấp nguồn gốc một cách tường minh.

createPayload(
  project: Project,
  input: ParsedArtifact | RecordEvent | DriftEvent,
  source?: PayloadSource
): PayloadEnvelope

Đối tượng nguồn từ chối trường thừa và tổ hợp không hợp lệ. Nguồn gốc tệp dùng cùng giới hạn cú pháp đường dẫn tương đối như hiện vật cục bộ.

Lớp vận chuyển được truyền vào

interface PayloadTransport {
  send(
    payload: PayloadEnvelope,
    context: { authorization: string }
  ): Promise<{ correlationId?: string }>
}

sendPayload kiểm tra và tạo vỏ bọc, phân giải thông tin xác thực rồi gọi giao diện do bên gọi cung cấp này. Nó không chọn điểm cuối hay cấu trúc kết nối giao thức.

Thông tin xác thực dùng tham chiếu env:NAME. resolveCredential đọc giá trị lúc chạy và từ chối giá trị thiếu hoặc chứa ký tự xuống dòng hay byte rỗng. Thông tin xác thực được truyền riêng trong ngữ cảnh vận chuyển và không bao giờ nằm trong vỏ bọc dữ liệu gửi.

await sendPayload(project, input, transport, {
  credentialRef: 'env:LANGDRIFT_TOKEN',
  source
})

SDK không cung cấp máy khách HTTP, lưu trữ, xử lý theo lô, hàng đợi nền, tự động thử lại hay tự động tải lên. Không đưa bí mật vào nội dung Markdown và dữ liệu Record vì các trường đó là nội dung được gửi.

Lỗi vận chuyển

Bộ điều hợp được truyền vào có thể ném TransportError(status). sendPayload ánh xạ:

401 hoặc 403 thành REMOTE_UNAUTHORIZED
các trạng thái 4xx khác thành REMOTE_REJECTED
mọi lỗi vận chuyển khác thành MCP_UNAVAILABLE

Chúng trở thành giá trị LangDriftError. Nội dung phản hồi từ xa nguyên gốc, dấu vết ngăn xếp và thông tin xác thực không được chuyển tiếp. Dữ liệu khi vận chuyển không khả dụng không được xếp hàng cục bộ; mọi lần thử lại đều phải được yêu cầu tường minh.