vue-agent-start 0.1.0

package/src/knowledge-hub/i18n/useKhI18n.ts

@@ -0,0 +1,107 @@
+/**
+ * useKhI18n — the internal i18n hook every component uses.
+ *
+ * `t('recall.hits', {n: 5})` looks up the key from the current locale, falls
+ * back to en-US, then to the raw key if truly missing.
+ *
+ * Locales are provided by wrapping the tree in <KhI18nProvider :locale="..."/>
+ * or by passing :locale directly on KnowledgeHubApp (which does the provide
+ * for us). Hosts can also override just a few keys — the hook deep-merges the
+ * provided partial over the default.
+ */
+import {
+  computed,
+  inject,
+  type InjectionKey,
+  provide,
+  ref,
+  type Ref,
+} from 'vue';
+
+import { DEFAULT_LOCALE, enUS, type KhMessages } from './messages';
+
+/** A partial locale — hosts only need to override the keys they change. */
+export type KhLocale =
+  | 'en-US'
+  | 'zh-CN'
+  | DeepPartial<KhMessages>;
+
+type DeepPartial<T> = {
+  [P in keyof T]?: DeepPartial<T[P]>;
+};
+
+const KEY: InjectionKey<Ref<KhMessages>> = Symbol('kh-i18n');
+
+function isPartial(v: KhLocale): v is DeepPartial<KhMessages> {
+  return typeof v === 'object' && v !== null;
+}
+
+function deepMerge<T>(base: T, override: DeepPartial<T>): T {
+  if (!override) return base;
+  const out: any = { ...base };
+  for (const k in override) {
+    const v = (override as any)[k];
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out[k] = deepMerge((base as any)[k], v);
+    } else if (v !== undefined) {
+      out[k] = v;
+    }
+  }
+  return out as T;
+}
+
+function resolveLocale(locale?: KhLocale): KhMessages {
+  if (locale === 'en-US') return enUS;
+  if (locale === 'zh-CN' || locale === undefined) return DEFAULT_LOCALE;
+  if (isPartial(locale)) {
+    return deepMerge(DEFAULT_LOCALE, locale);
+  }
+  return DEFAULT_LOCALE;
+}
+
+/**
+ * KnowledgeHubApp calls this in its setup so every descendant gets the same
+ * message catalog. Passing a new `locale` prop updates it reactively.
+ */
+export function provideKhI18n(locale: () => KhLocale | undefined) {
+  const messages = ref<KhMessages>(resolveLocale(locale()));
+  // A simple watcher wouldn't work here because we don't want a vue-watcher
+  // dep for the module — refresh manually on next tick by re-calling the fn.
+  // Consumers who need reactivity can pass a locale that never changes, or
+  // remount KnowledgeHubApp with the new locale.
+  provide(KEY, messages);
+  return messages;
+}
+
+/**
+ * Every component uses this. Returns `t(key, params?)` — key is dot-separated
+ * ('recall.hits'); params is a `{name}` map interpolated into the string.
+ */
+export function useKhI18n() {
+  const messages = inject(KEY, ref(DEFAULT_LOCALE));
+
+  const t = (path: string, params?: Record<string, number | string>): string => {
+    const parts = path.split('.');
+    let cur: any = messages.value;
+    for (const p of parts) {
+      cur = cur?.[p];
+      if (cur === undefined) break;
+    }
+    if (typeof cur !== 'string') {
+      // Fall back to en-US
+      cur = enUS;
+      for (const p of parts) {
+        cur = cur?.[p];
+        if (cur === undefined) break;
+      }
+      if (typeof cur !== 'string') return path;
+    }
+    if (!params) return cur;
+    return cur.replaceAll(/\{(\w+)\}/g, (_, k) => String(params[k] ?? `{${k}}`));
+  };
+
+  return {
+    t,
+    messages: computed(() => messages.value),
+  };
+}

package/src/knowledge-hub/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @agent-start/knowledge-hub — public entry point.
+ *
+ * See README.md for usage. Quick recap:
+ *
+ *   import { KnowledgeHubApp, createSpringAgentStartAdapter } from '@agent-start/knowledge-hub'
+ *   import '@agent-start/knowledge-hub/style.css'
+ *
+ *   <KnowledgeHubApp :api="createSpringAgentStartAdapter({baseUrl: '/api/agent-start'})" />
+ *
+ * Consumers with a non-spring-agent-start backend implement the `KnowledgeHubApi`
+ * interface themselves (see types/api.ts — it's split into small sub-interfaces
+ * so partial implementations are easy).
+ */
+
+// --- Style tokens (defaults). Consumers can also import '@agent-start/knowledge-hub/style.css'
+// separately if they want to control when the CSS is injected.
+import './styles/index.css';
+
+// --- Drop-in top-level
+export { default as KnowledgeHubApp } from './components/KnowledgeHubApp.vue';
+
+// --- Building blocks
+export { default as CreateDatasetWizard } from './components/CreateDatasetWizard.vue';
+export { default as DatasetCardGrid } from './components/DatasetCardGrid.vue';
+export { default as DatasetDetailDrawer } from './components/DatasetDetailDrawer.vue';
+export { default as DatasetSettingsPanel } from './components/DatasetSettingsPanel.vue';
+export { default as DatasetSidebar } from './components/DatasetSidebar.vue';
+export { default as DocumentChunksView } from './components/DocumentChunksView.vue';
+export { default as DocumentTable } from './components/DocumentTable.vue';
+export { default as RecallTestingPanelV2 } from './components/RecallTestingPanelV2.vue';
+
+// --- Legacy widgets (still used by /workflow KNOWLEDGE_RETRIEVAL node etc.)
+export { default as DatasetPicker } from './components/DatasetPicker.vue';
+export { default as DatasetPickerModal } from './components/DatasetPickerModal.vue';
+export { default as HitTestingPanel } from './components/HitTestingPanel.vue';
+export { default as RetrievedList } from './components/RetrievedList.vue';
+
+// --- Adapters (implement KnowledgeHubApi against a known backend)
+export { createSpringAgentStartAdapter } from './adapters/springAgentStart';
+
+// --- Composables
+export * from './composables/useKnowledge';
+
+// --- All types re-exported from a single surface
+export * from './types';

package/src/knowledge-hub/styles/index.css

@@ -0,0 +1,4 @@
+/* Entry stylesheet — hosts import this once at their app entry:
+     import '@agent-start/knowledge-hub/style.css'
+   Everything else is composed of design tokens declared in tokens.css. */
+@import './tokens.css';

package/src/knowledge-hub/styles/tokens.css

@@ -0,0 +1,138 @@
+/**
+ * Design tokens for @agent-start/knowledge-hub.
+ *
+ * These are the ONLY colors, radii and shadows the components should reference.
+ * A host that wants to rebrand overrides them at the root:
+ *
+ *   :root {
+ *     --kh-color-primary: #ff6600;
+ *     --kh-color-primary-strong: #cc4d00;
+ *   }
+ *
+ * A dark ruleset ships out of the box — flip it by setting `data-theme="dark"`
+ * on any ancestor of the components.
+ */
+
+:root {
+  /* ------- Color: brand */
+  --kh-color-primary: #6366f1;
+  --kh-color-primary-strong: #4f46e5;
+  --kh-color-primary-soft: #eef2ff;
+  --kh-color-primary-contrast: #ffffff;
+  --kh-color-primary-outline: rgba(99, 102, 241, 0.15);
+
+  /* ------- Color: neutrals (text + surface) */
+  --kh-color-text-primary: #0f172a;
+  --kh-color-text-secondary: #334155;
+  --kh-color-text-tertiary: #64748b;
+  --kh-color-text-muted: #94a3b8;
+  --kh-color-text-inverse: #ffffff;
+
+  --kh-color-surface: #ffffff;
+  --kh-color-surface-raised: #ffffff;
+  --kh-color-surface-sunken: #f8fafc;
+  --kh-color-surface-hover: #f1f5f9;
+
+  --kh-color-border: #e2e8f0;
+  --kh-color-border-hover: #cbd5e1;
+  --kh-color-border-strong: #94a3b8;
+  --kh-color-divider: #f1f5f9;
+
+  /* ------- Color: semantic */
+  --kh-color-success: #059669;
+  --kh-color-success-soft: #dcfce7;
+  --kh-color-warning: #b45309;
+  --kh-color-warning-soft: #fef3c7;
+  --kh-color-danger: #dc2626;
+  --kh-color-danger-soft: #fef2f2;
+  --kh-color-info: #4338ca;
+  --kh-color-info-soft: #eef4ff;
+
+  /* ------- Radius */
+  --kh-radius-xs: 4px;
+  --kh-radius-sm: 6px;
+  --kh-radius-md: 8px;
+  --kh-radius-lg: 12px;
+  --kh-radius-xl: 16px;
+  --kh-radius-round: 50%;
+
+  /* ------- Spacing */
+  --kh-space-1: 4px;
+  --kh-space-2: 8px;
+  --kh-space-3: 12px;
+  --kh-space-4: 16px;
+  --kh-space-5: 20px;
+  --kh-space-6: 24px;
+
+  /* ------- Font sizes */
+  --kh-fs-xs: 10px;
+  --kh-fs-sm: 11px;
+  --kh-fs-md: 12px;
+  --kh-fs-lg: 13px;
+  --kh-fs-xl: 14px;
+  --kh-fs-2xl: 15px;
+  --kh-fs-3xl: 18px;
+
+  /* ------- Shadows */
+  --kh-shadow-sm: 0 1px 2px rgba(15, 23, 42, 0.04);
+  --kh-shadow-md: 0 3px 12px rgba(15, 23, 42, 0.06);
+  --kh-shadow-lg: 0 4px 14px rgba(15, 23, 42, 0.08);
+  --kh-shadow-drawer: -6px 0 22px rgba(15, 23, 42, 0.14);
+  --kh-shadow-modal: 0 20px 60px rgba(15, 23, 42, 0.25);
+
+  /* ------- Transition */
+  --kh-tx-fast: 0.15s ease;
+
+  /* ------- z-index (mostly for drawer/modal stacking) */
+  --kh-z-drawer: 1040;
+  --kh-z-modal: 1050;
+
+  /* ------- Focus ring */
+  --kh-focus-ring: 0 0 0 3px var(--kh-color-primary-outline);
+
+  /* ------- Component-level (composed from primitives) */
+  --kh-card-bg: var(--kh-color-surface);
+  --kh-card-border: var(--kh-color-border);
+  --kh-card-radius: var(--kh-radius-lg);
+  --kh-card-shadow-hover: var(--kh-shadow-lg);
+
+  --kh-input-bg: var(--kh-color-surface);
+  --kh-input-border: #d1d5db;
+  --kh-input-radius: var(--kh-radius-md);
+}
+
+/* Dark mode overrides — flipped by setting data-theme="dark" on any ancestor. */
+[data-theme='dark'] {
+  --kh-color-primary: #818cf8;
+  --kh-color-primary-strong: #6366f1;
+  --kh-color-primary-soft: rgba(129, 140, 248, 0.15);
+  --kh-color-primary-contrast: #ffffff;
+  --kh-color-primary-outline: rgba(129, 140, 248, 0.3);
+
+  --kh-color-text-primary: #f3f4f6;
+  --kh-color-text-secondary: #d1d5db;
+  --kh-color-text-tertiary: #9ca3af;
+  --kh-color-text-muted: #6b7280;
+  --kh-color-text-inverse: #0f172a;
+
+  --kh-color-surface: #1f2937;
+  --kh-color-surface-raised: #262f3d;
+  --kh-color-surface-sunken: #171e2b;
+  --kh-color-surface-hover: #2d3748;
+
+  --kh-color-border: #374151;
+  --kh-color-border-hover: #4b5563;
+  --kh-color-border-strong: #6b7280;
+  --kh-color-divider: #2d3748;
+
+  --kh-color-success-soft: rgba(16, 185, 129, 0.15);
+  --kh-color-warning-soft: rgba(217, 119, 6, 0.15);
+  --kh-color-danger-soft: rgba(220, 38, 38, 0.15);
+  --kh-color-info-soft: rgba(99, 102, 241, 0.15);
+
+  --kh-input-border: #4b5563;
+
+  --kh-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
+  --kh-shadow-md: 0 3px 12px rgba(0, 0, 0, 0.4);
+  --kh-shadow-lg: 0 4px 14px rgba(0, 0, 0, 0.5);
+}

package/src/knowledge-hub/types/api.ts

@@ -0,0 +1,213 @@
+/**
+ * The API contract KnowledgeHubApp needs. Split into 5 sub-interfaces so a
+ * host can implement a partial (e.g. a read-only viewer only needs
+ * DatasetsReadApi + DocumentsReadApi + RetrievalApi).
+ *
+ * `KnowledgeHubApi` is a type union of every sub-interface — code that
+ * accepts one can accept any richer implementation.
+ */
+import type { Chunk, DocMetadata, DocumentRow } from './document';
+import type {
+  DatasetCardItem,
+  DatasetSummary,
+  IndexingTechnique,
+  ProcessRule,
+  RetrievalConfig,
+} from './dataset';
+import type { RecallHit, RecentQuery } from './retrieval';
+
+// ------- datasets
+export interface DatasetsApi {
+  listDatasets(): Promise<DatasetCardItem[]>;
+  getDataset(id: string): Promise<DatasetSummary>;
+  createDataset(req: {
+    name: string;
+    description?: string;
+    embeddingModelId?: string;
+    indexingTechnique?: IndexingTechnique;
+    processRule?: ProcessRule;
+    retrievalConfig?: RetrievalConfig;
+  }): Promise<DatasetCardItem>;
+  updateDataset(
+    id: string,
+    patch: Partial<DatasetSummary> & Record<string, unknown>,
+  ): Promise<DatasetSummary>;
+  deleteDataset(id: string): Promise<void>;
+}
+
+// ------- documents
+export interface DocumentsApi {
+  listDocuments(datasetId: string): Promise<DocumentRow[]>;
+  uploadDocument(datasetId: string, file: File): Promise<void>;
+  deleteDocument(datasetId: string, docId: string): Promise<void>;
+  setDocumentEnabled?(
+    datasetId: string,
+    docId: string,
+    enabled: boolean,
+  ): Promise<void>;
+  /**
+   * Preview how a file would be chunked under a given {@link ProcessRule}
+   * without touching the DB or the vector store. Used by the wizard's
+   * "文本分段与清洗" step so the preview reflects the real ingestion result
+   * (same reader → same cleaner → same chunker as on save). Backends that
+   * don't implement it get the wizard's mock preview as a fallback.
+   *
+   * @param file  raw file bytes the user just picked
+   * @param rule  the currently-editing {@link ProcessRule}
+   * @param limit max chunks to return; server may cap further
+   */
+  previewChunks?(
+    file: File,
+    rule: ProcessRule,
+    limit?: number,
+  ): Promise<ChunkPreview>;
+}
+
+/**
+ * Response shape of {@link DocumentsApi.previewChunks}. {@code totalChunks}
+ * is the full chunker output; {@code chunks} is truncated to {@code limit}.
+ */
+export interface ChunkPreview {
+  totalChunks: number;
+  chunks: Array<{ index: number; text: string; tokens: number }>;
+}
+
+// ------- segments
+export interface SegmentsApi {
+  /**
+   * Paged fetch of a document's segments. `page` is 1-indexed; when omitted the
+   * host implementation is expected to return the first page with a sensible
+   * default page size. The total comes from {@link DocMetadata#totalChunks} —
+   * kept out of this response to avoid an extra count query on hot paths.
+   */
+  listSegments(
+    datasetId: string,
+    docId: string,
+    page?: number,
+    pageSize?: number,
+  ): Promise<Chunk[]>;
+  loadDocumentMetadata(datasetId: string, docId: string): Promise<DocMetadata>;
+  updateSegment(
+    datasetId: string,
+    docId: string,
+    segId: string,
+    content: string,
+  ): Promise<Chunk>;
+  deleteSegment(datasetId: string, docId: string, segId: string): Promise<void>;
+  setSegmentEnabled(
+    datasetId: string,
+    docId: string,
+    segId: string,
+    enabled: boolean,
+  ): Promise<Chunk>;
+  appendSegment?(
+    datasetId: string,
+    docId: string,
+    content: string,
+  ): Promise<Chunk>;
+}
+
+// ------- retrieval
+export interface RetrievalApi {
+  retrieve(
+    datasetId: string,
+    req: { query: string; method: string; topK?: number },
+  ): Promise<RecallHit[]>;
+  listRecallHistory(datasetId: string, limit?: number): Promise<RecentQuery[]>;
+}
+
+// ------- models
+/**
+ * Embedding-model list entry. {@code providerName} is optional but recommended —
+ * when present, the settings panel groups the dropdown by provider and shows a
+ * brand icon for each row. {@code providerLabel} is a display label; falls back
+ * to {@code providerName} when omitted.
+ */
+export interface EmbeddingModelOption {
+  id: string;
+  label: string;
+  providerName?: string;
+  providerLabel?: string;
+  /** Marks the tenant-default embedding model — the panel auto-selects it. */
+  isDefault?: boolean;
+}
+
+export interface ModelsApi {
+  listEmbeddingModels(): Promise<EmbeddingModelOption[]>;
+  /**
+   * Optional — list rerank models the wizard's 检索设置 offers. Hosts that don't
+   * implement it get an empty dropdown (rerank stays off).
+   */
+  listRerankModels?(): Promise<Array<{ id: string; label: string }>>;
+  /**
+   * Optional — resolve the tenant-scoped default embedding model id (from
+   * {@code /models/defaults} on the spring-agent-start backend). When present,
+   * the settings panel pre-fills the picker if the dataset itself has none.
+   */
+  getDefaultEmbeddingModelId?(): Promise<null | string>;
+}
+
+// ------- side effects (all optional)
+export interface KnowledgeHubHooks {
+  /** Toast success. */
+  onSuccess?(message: string): void;
+  /** Toast failure. */
+  onError?(message: string): void;
+  /** Called by the sidebar's ⌘ 访问 API button. */
+  onCopyApi?(datasetId: string): void;
+  /**
+   * Called when the built-in "先注册 Embedding 模型" empty-state nudge is
+   * clicked. Hosts wire this to their model-management route so the user
+   * can register an embedding model without leaving the flow. When omitted
+   * the nudge card renders without a button.
+   */
+  onGoToEmbeddingSetup?(): void;
+}
+
+/**
+ * The bag of async operations KnowledgeHubApp needs. Consumers implement this
+ * shape (typically by wrapping their existing REST client — or by calling
+ * `createSpringAgentStartAdapter` if their backend is spring-agent-start itself).
+ */
+export type KnowledgeHubApi = DatasetsApi &
+  DocumentsApi &
+  SegmentsApi &
+  RetrievalApi &
+  ModelsApi &
+  KnowledgeHubHooks;
+
+/**
+ * Subset used by DatasetDetailDrawer. Standalone (not `extends`) because it
+ * exposes `loadDataset` + `uploadDocuments` (plural, batch semantic) rather
+ * than the {@link DatasetsApi#getDataset} + {@link DocumentsApi#uploadDocument}
+ * atoms. Hosts that only need the drawer implement this smaller surface.
+ */
+export interface DatasetDetailHub extends SegmentsApi, RetrievalApi, ModelsApi {
+  loadDataset(id: string): Promise<DatasetSummary>;
+  updateDataset(
+    id: string,
+    patch: Partial<DatasetSummary> & Record<string, unknown>,
+  ): Promise<DatasetSummary>;
+  deleteDataset(id: string): Promise<void>;
+
+  listDocuments(datasetId: string): Promise<DocumentRow[]>;
+  uploadDocuments(datasetId: string, files: File[]): Promise<void>;
+  deleteDocument(datasetId: string, docId: string): Promise<void>;
+  setDocumentEnabled?(
+    datasetId: string,
+    docId: string,
+    enabled: boolean,
+  ): Promise<void>;
+  /**
+   * Preview how a file would be chunked, for the add-documents wizard's
+   * step-2 pane. Same shape as {@link DocumentsApi.previewChunks}. Optional —
+   * when the host adapter omits it, the wizard falls back to a mock preview.
+   */
+  previewChunks?(
+    file: File,
+    rule: ProcessRule,
+    limit?: number,
+  ): Promise<ChunkPreview>;
+
+  onCopyApi?(datasetId: string): void;
+}

package/src/knowledge-hub/types/dataset.ts

@@ -0,0 +1,88 @@
+/**
+ * Dataset-level types. Mirror the spring-agent-web JSON contract, but the
+ * module has no hard dependency on that backend — any REST source that returns
+ * these shapes works.
+ */
+
+export type IndexingTechnique = 'ECONOMY' | 'HIGH_QUALITY';
+
+/**
+ * Slim dataset view suitable for the card grid. Only the visual fields are
+ * required — a partial-shape backend still works, the card just shows less.
+ */
+export interface DatasetCardItem {
+  id: string;
+  name: string;
+  description?: string;
+  documentCount?: number;
+  segmentCount?: number;
+  indexingTechnique?: IndexingTechnique;
+  updatedAt?: string;
+}
+
+/**
+ * Full dataset shape for the detail view. Optional JSON-blob fields
+ * (`retrievalConfigJson`, `processRuleJson`) are strings so the module can
+ * parse them defensively without coupling to a specific config schema.
+ */
+export interface DatasetSummary {
+  id: string;
+  name: string;
+  description?: string;
+  documentCount?: number;
+  segmentCount?: number;
+  indexingTechnique?: IndexingTechnique;
+  embeddingModelId?: string;
+  retrievalConfigJson?: string;
+  processRuleJson?: string;
+}
+
+/** Legacy alias kept for backwards compat with older Dify-style flows. */
+export interface Dataset extends DatasetSummary {
+  tenantId?: string;
+}
+
+/** Navigation tabs of the dataset detail view. */
+export type DatasetTab = 'documents' | 'recall' | 'settings';
+
+// --------- process rule (chunking) -----------------------------------------
+
+export type ChunkingTemplate =
+  | 'NAIVE'
+  | 'PARENT_CHILD'
+  | 'QA'
+  | 'MARKDOWN'
+  | 'ONE';
+
+export type ParentMode = 'PARAGRAPH' | 'FULL_DOC';
+
+/**
+ * Wire shape of the backend `ProcessRule`. Only fields the wizard writes are
+ * enumerated — hosts can send extras and the backend just ignores them.
+ */
+export interface ProcessRule {
+  template?: ChunkingTemplate;
+  chunkTokens?: number;
+  overlapTokens?: number;
+  parentChunkTokens?: number;
+  parentMode?: ParentMode;
+  separators?: string[];
+  removeExtraWhitespace?: boolean;
+  removeUrlsEmails?: boolean;
+}
+
+// --------- retrieval config -------------------------------------------------
+// Note: RetrievalMethod itself lives in ./retrieval to keep the retrieval module
+// self-contained; we import it here just for RetrievalConfig.
+import type { RetrievalMethod } from './retrieval';
+
+/** Wire shape of the backend `RetrievalConfig`. */
+export interface RetrievalConfig {
+  method?: RetrievalMethod;
+  topK?: number;
+  scoreThreshold?: number;
+  vectorWeight?: number;
+  rerankEnabled?: boolean;
+  rerankModelId?: string;
+  rerankerName?: string;
+}

package/src/knowledge-hub/types/document.ts

@@ -0,0 +1,45 @@
+/**
+ * Document + chunk (segment) types.
+ */
+
+/** One row in the DocumentTable. */
+export interface DocumentRow {
+  id: string;
+  name: string;
+  /** "自定义" / "父子分段" — display string, not enum. */
+  chunkMode?: string;
+  wordCount?: number;
+  hitCount?: number;
+  uploadedAt?: string;
+  status: 'AVAILABLE' | 'FAILED' | 'PROCESSING';
+  enabled: boolean;
+}
+
+/** One chunk shown in DocumentChunksView. */
+export interface Chunk {
+  id: string;
+  position: number;
+  content: string;
+  tokenCount?: number;
+  charCount?: number;
+  hitCount?: number;
+  enabled: boolean;
+  keywords?: string[];
+}
+
+/** Right-side metadata pane of DocumentChunksView. */
+export interface DocMetadata {
+  fileName?: string;
+  kind?: string;
+  size?: string;
+  uploadedAt?: string;
+  parsedAt?: string;
+  embeddedAt?: string;
+  chunkMode?: string;
+  chunkMaxSize?: number;
+  totalChars?: number;
+  totalChunks?: number;
+  avgChunkChars?: number;
+  avgEmbedMs?: number;
+  totalTokens?: number;
+}

package/src/knowledge-hub/types/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Public type surface of @agent-start/knowledge-hub. Everything a consumer might
+ * need to type their host code is re-exported here.
+ */
+
+export * from './api';
+export * from './dataset';
+export * from './document';
+export * from './retrieval';

package/src/knowledge-hub/types/retrieval.ts

@@ -0,0 +1,46 @@
+/**
+ * Retrieval / hit-testing types.
+ */
+
+export type RetrievalMethod = 'FULL_TEXT' | 'HYBRID' | 'VECTOR';
+
+export interface RetrieveRequest {
+  query: string;
+  method?: RetrievalMethod;
+  topK?: number;
+  scoreThreshold?: number;
+  vectorWeight?: number;
+  metadataFilter?: Record<string, unknown>;
+}
+
+/** Row in the retrieval result list — from HybridRetriever. */
+export interface RetrievedSegment {
+  segmentId: string;
+  datasetId: string;
+  documentId: string;
+  position: number;
+  content: string;
+  parentContent?: string;
+  vectorScore: number;
+  keywordScore: number;
+  score: number;
+  metadata?: Record<string, unknown>;
+}
+
+/** One row in the RecallTestingPanel result pane. Simpler than RetrievedSegment. */
+export interface RecallHit {
+  segmentId: string;
+  content: string;
+  position?: number;
+  score: number;
+  documentName?: string;
+}
+
+/** Historical recall query row shown in the "记录" list. */
+export interface RecentQuery {
+  id: string;
+  query: string;
+  method: string;
+  hitCount: number;
+  at: string;
+}