酬載與傳輸

封套

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

account_id 和 project_id 來自已驗證的專案。它們提供酬載的路由與背景，不是憑證，也不授權存取。 resource 是支柱與類型，例如 vision.prd；resource_id 則是產出物或事件 ID。

Markdown 產出物的 payload 為 { metadata, body }。 Record 和 Drift Event 酬載是已驗證的 JSON 封套。 references 是從已驗證輸入取得的明確參照。

來源資訊

PayloadSource.kind 為以下其中之一：

markdown — 需要安全的相對 path
json — 需要安全的相對 path
integration — 需要 integration 和 external_id

已解析的產出物會依路徑推定 markdown 或 json。直接提供的 Record 會推定其整合來源。直接提供的 Drift Event 沒有來源欄位，因此呼叫端必須明確提供來源資訊。

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

來源物件會拒絕額外欄位與無效組合。檔案來源使用與本機產出物相同的相對路徑語法限制。

注入式傳輸

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

sendPayload 會驗證並建構封套、解析憑證，然後呼叫由呼叫端提供的介面。它不會選擇端點或協定拓撲。

憑證使用 env:NAME 參照。 resolveCredential 會在執行時讀取值，並拒絕缺少的值，或包含換行或空位元組的值。憑證會在傳輸背景中獨立傳遞，絕不包含在酬載封套內。

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

SDK 不提供 HTTP 用戶端、持久儲存、批次處理、背景佇列、自動重試或自動上傳。 Markdown 本文與 Record 資料會成為酬載內容，因此請勿將機密放入這些欄位。

傳輸錯誤

注入的介接器可拋出 TransportError(status)。 sendPayload 的對應如下：

401 或 403 對應至 REMOTE_UNAUTHORIZED
其他 4xx 狀態對應至 REMOTE_REJECTED
其餘所有傳輸失敗對應至 MCP_UNAVAILABLE

這些錯誤會成為 LangDriftError。原始遠端回應本文、堆疊與憑證不會向外傳遞。傳輸不可用時，資料不會在本機排入佇列；任何重試都必須明確執行。