套件 API

這是 TypeScript 套件的參考文件。它不是 HTTP API，也不定義後端路由。

`@langdrift/sdk`

根進入點會重新匯出每個公開 SDK 模組。專用的 /schema、/mcp 與 /integrations 進入點，則提供各自領域中相同的匯出項目。

協定型別

執行時常數：

ARTIFACT_TYPES
SCHEMA_VERSION

公開型別：

ArtifactType、DocumentType 和 Pillar
JsonValue 和 JsonObject
ArtifactRef 和 ActorRef
Project、ArtifactMetadata、RecordEvent 和 DriftEvent

結構定義與驗證

執行時結構定義匯出項目為 schemas、projectSchema、pillarSchemas 與 artifactPillars。

validateProject(input: unknown): Project
validateArtifact(input: unknown): ArtifactMetadata
validateRecord(input: unknown): RecordEvent
validateDrift(input: unknown): DriftEvent

這些函式為同步操作，會傳回已驗證的原始物件。它們不會強制轉換或複製資料，而是拋出 LangDriftError。

安全路徑、專案與產出物

findRepositoryRoot(start?: string): Promise<string>
resolveSafePath(root: string, relative: string): Promise<string>
readProjectFile(
  root: string,
  relative: string,
  maxBytes?: number
): Promise<string>
loadProject(root: string): Promise<Project>
parseArtifact(text: string, artifactPath: string): ParsedArtifact
discoverArtifacts(
  root: string,
  options?: DiscoveryOptions
): Promise<ParsedArtifact[]>

也匯出 MAX_ARTIFACT_BYTES、artifactLocations 和 artifactReferences。相關型別為 ParsedArtifact 和 DiscoveryOptions。

參照與事件

resolveReferences(
  root: string,
  artifacts: ParsedArtifact[],
  knownReferences?: ArtifactRef[]
): Promise<ReferenceResolution>
 
recordId(
  integration: string,
  sourceId: string,
  eventId: string
): string
 
createRecord(
  input: Omit<RecordEvent, 'type' | 'schema_version'>
): RecordEvent
 
createDrift(
  input: Omit<DriftEvent, 'type' | 'schema_version'>
): DriftEvent

ReferenceResolution 也有匯出。 recordId、createRecord 和 createDrift 為同步操作。

酬載與傳輸

createPayload(
  project: Project,
  input: ParsedArtifact | RecordEvent | DriftEvent,
  source?: PayloadSource
): PayloadEnvelope
 
resolveCredential(
  reference: string,
  environment?: Readonly<Record<string, string | undefined>>
): string
 
sendPayload(
  project: Project,
  artifact: ParsedArtifact | RecordEvent | DriftEvent,
  transport: PayloadTransport,
  options: {
    credentialRef: string
    environment?: Readonly<Record<string, string | undefined>>
    source?: PayloadSource
  }
): Promise<TransportResult>

公開傳輸型別為 PayloadSource、PayloadEnvelope、PayloadTransport 和 TransportResult。 TransportError 是僅含狀態的錯誤；注入的介接器可拋出它，交由 sendPayload 分類。

整合與診斷

recordFromGitHubPullRequest(
  event: GitHubPullRequestEvent,
  references?: ArtifactRef[],
  details?: GitHubPullRequestDetails
): RecordEvent
 
reportError(error: unknown, logger: Logger): void

套件也匯出 integrationCapabilities、RecordSourceAdapter、GitHubPullRequestEvent、GitHubPullRequestDetails、LangDriftError、Issue、Diagnostic 和 Logger。

`@langdrift/core`

planSetup(options?: SetupOptions): Promise<SetupPlan>
setupProject(options?: SetupOptions): Promise<SetupResult>

套件匯出 SetupError，以及 SetupOptions、SetupFile、SetupPlan 和 SetupResult 型別。 runCli、範本與產生器內部實作不是套件匯出項目。

planSetup 會驗證與讀取，不會寫入。 setupProject 在取得無衝突計畫後，只會寫入安全的 create 項目；試跑時則原樣傳回計畫。

錯誤

SDK 的驗證、路徑、憑證與傳輸使用帶有 code 和 issues: { path, message }[] 的 LangDriftError。設定專屬的失敗使用帶有 code、files 和 fields 的 SetupError。專案或路徑驗證失敗時，設定也可能傳出 SDK 的 LangDriftError。

只有明確傳回 Promise 的函式是非同步。這些套件中的 API 都不會隱含記錄日誌、遠端查詢、上傳或重試。