Tham chiếu

Tham chiếu là dữ liệu giao thức tường minh. SDK không suy ra chúng từ văn xuôi, tiêu đề, tên nhánh hoặc URL của nhà cung cấp.

interface ArtifactRef {
  type: string
  id: string
  path?: string
  integration?: string
  external_id?: string
}

type và id tạo thành định danh giao thức. path có thể giới hạn một tham chiếu cục bộ vào một đường dẫn hiện vật. integration và external_id phải cùng có hoặc cùng không có đối với định danh bên ngoài.

Siêu dữ liệu tài liệu có thể cung cấp references, supersedes, superseded_by và các mảng quan hệ có kiểu như research, specs hoặc vision_targets. Trường external: { integration, id } đăng ký định danh của chính tài liệu tại nhà cung cấp làm tham chiếu bên ngoài. Drift Events cũng tham chiếu vision_target_id của chúng.

Phân giải một tập hợp

const resolution = await resolveReferences(
  root,
  artifacts,
  [{ type: 'vision-target', id: 'VT-001' }]
)

Quá trình phân giải lập chỉ mục hiện vật cục bộ theo cặp (type, id) chính xác.

• Định danh cục bộ khớp được đánh dấu resolved. Nếu tham chiếu có path, đường dẫn đó phải bằng đường dẫn hiện vật đích.
• Tham chiếu có integration và external_id được đánh dấu external.
• Tham chiếu không có đường dẫn và khớp đối số thứ ba tùy chọn cũng là external. Danh sách này là sổ đăng ký tường minh các định danh mà bên gọi đã biết.
• Các trường hợp khác tạo vấn đề REFERENCE_NOT_FOUND.
• Chu trình giữa các tham chiếu cục bộ đã phân giải tạo vấn đề REFERENCE_CYCLE.

Các vấn đề được trả về trong resolution.issues; tham chiếu thiếu và chu trình không ném ngoại lệ. Định danh cục bộ (type, id) trùng lặp gây mơ hồ và ném LangDriftError với mã ARTIFACT_INVALID.

Đường dẫn tham chiếu trải qua cùng kiểm tra đường dẫn an toàn như hiện vật. Một đường dẫn không kích hoạt tra cứu từ xa, và danh sách tham chiếu đã biết không truy vấn hay chứng minh dữ liệu tồn tại ở hệ thống phía máy chủ. Phân giải chỉ diễn ra cục bộ và phải được xem là bước kiểm tra riêng trước khi vận chuyển dữ liệu.