@tablestore/tablestore-agent-cli 0.1.8 → 0.2.0

package/dist/dashboard-runtime/dashboard/src/schemas/instance.ts

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+/**
+ * Instance name constraints mirror packages/shared INSTANCE_NAME_PATTERN
+ * (`^[a-z0-9-]{1,32}$`) plus the reserved "default" exclusion.
+ */
+const instanceNameSchema = z
+  .string()
+  .trim()
+  .regex(/^[a-z0-9-]{1,32}$/, "名称需为 1-32 位小写字母、数字或连字符")
+  .refine((v) => v !== "default", "名称 \"default\" 为保留字");
+
+const trimmedNonEmpty = (label: string, max = 512) =>
+  z.string().trim().min(1, `请输入${label}`).max(max);
+
+const optionalTrimmed = (max = 512) =>
+  z.string().trim().max(max).optional().or(z.literal(""));
+
+export const connectInstanceSchema = z.object({
+  name: instanceNameSchema,
+  accessKeyId: trimmedNonEmpty("AccessKey ID", 128),
+  accessKeySecret: trimmedNonEmpty("AccessKey Secret", 512),
+  otsEndpoint: trimmedNonEmpty("OTS Endpoint", 256),
+  otsInstanceName: trimmedNonEmpty("OTS 实例名", 128),
+  ossEndpoint: optionalTrimmed(256),
+  ossBucketName: optionalTrimmed(128),
+  region: optionalTrimmed(64),
+  activate: z.boolean().optional(),
+});
+
+export const updateInstanceSchema = z
+  .object({
+    accessKeyId: optionalTrimmed(128),
+    accessKeySecret: optionalTrimmed(512),
+    otsEndpoint: optionalTrimmed(256),
+    otsInstanceName: optionalTrimmed(128),
+    ossEndpoint: optionalTrimmed(256),
+    ossBucketName: optionalTrimmed(128),
+    region: optionalTrimmed(64),
+    activate: z.boolean().optional(),
+  })
+  // Require AccessKey ID and Secret to be supplied together. Passing only
+  // one of the pair previously sneaked past validation and later tripped a
+  // generic 500 on the server side where the pair is encoded as a single
+  // credential. Matching both at the schema layer surfaces the mistake in
+  // the form itself with a field-targeted message.
+  .refine(
+    (v) => {
+      const hasId = Boolean(v.accessKeyId && v.accessKeyId.length > 0);
+      const hasSecret = Boolean(v.accessKeySecret && v.accessKeySecret.length > 0);
+      return hasId === hasSecret;
+    },
+    {
+      message: "AccessKey ID 与 Secret 必须成对更新，要么同时填写、要么同时留空",
+      path: ["accessKeySecret"],
+    },
+  );
+
+/**
+ * Form-side schema for editing an existing instance. Mirrors
+ * {@link updateInstanceSchema} on the server: every field is optional and
+ * AccessKey ID/Secret must be filled in pairs (or both left blank to keep
+ * the existing credential intact). Used by the connect-instance form when
+ * `mode === "edit"` so the dialog can prepopulate placeholders without
+ * clobbering the live credential when the user only wants to change, say,
+ * the OSS bucket.
+ */
+export const editInstanceFormSchema = z
+  .object({
+    name: instanceNameSchema,
+    accessKeyId: optionalTrimmed(128),
+    accessKeySecret: optionalTrimmed(512),
+    otsEndpoint: trimmedNonEmpty("OTS Endpoint", 256),
+    otsInstanceName: trimmedNonEmpty("OTS 实例名", 128),
+    ossEndpoint: optionalTrimmed(256),
+    ossBucketName: optionalTrimmed(128),
+    region: optionalTrimmed(64),
+    activate: z.boolean().optional(),
+  })
+  .refine(
+    (v) => {
+      const hasId = Boolean(v.accessKeyId && v.accessKeyId.length > 0);
+      const hasSecret = Boolean(
+        v.accessKeySecret && v.accessKeySecret.length > 0,
+      );
+      return hasId === hasSecret;
+    },
+    {
+      message:
+        "AccessKey ID 与 Secret 必须成对更新，要么同时填写、要么同时留空",
+      path: ["accessKeySecret"],
+    },
+  );
+
+export const importInstanceSchema = z.object({
+  // Match the client-side Textarea guard (min 10) so server and browser
+  // reject identical inputs; the previous 1-char floor let obvious
+  // typos (e.g. a stray "a") reach the decoder which returned a
+  // cryptic INVALID_TOKEN at submit time.
+  token: z.string().trim().min(10, "Token 长度不足，无法解析").max(4096),
+  name: instanceNameSchema.optional(),
+  activate: z.boolean().optional(),
+});
+
+export type ConnectInstanceInput = z.infer<typeof connectInstanceSchema>;
+export type UpdateInstanceInput = z.infer<typeof updateInstanceSchema>;
+export type ImportInstanceInput = z.infer<typeof importInstanceSchema>;

package/dist/dashboard-runtime/dashboard/src/schemas/llm-chat.ts

@@ -25,6 +25,7 @@ export const chatRagSchema = z.object({
  * the schema so we can emit a friendlier SSE error frame.
  */
 export const chatRequestSchema = z.object({
+  activeInstance: z.string().min(1).nullable().optional(),
   providerId: z.string().min(1),
   model: z.string().min(1),
   messages: z.array(chatMessageWireSchema).min(1),

package/dist/dashboard-runtime/dashboard/src/schemas/retrieval.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const retrievalSchema = z.object({
+  knowledgeBaseName: z.string().min(1),
+  query: z
+    .string()
+    .min(1, "Query must be at least 1 character")
+    .max(128, "Query must be at most 128 characters"),
+  subspace: z.array(z.string()).optional(),
+  topK: z.number().int().min(1).max(100).default(20).optional(),
+  searchType: z
+    .array(z.enum(["DENSE_VECTOR", "FULL_TEXT"]))
+    .optional(),
+  rerankType: z.enum(["RRF", "WEIGHT", "MODEL"]).optional(),
+  // RRF parameters
+  rrfK: z.number().int().min(1).optional(),
+  rrfDenseWeight: z.number().min(0).optional(),
+  rrfFullTextWeight: z.number().min(0).optional(),
+  // WEIGHT parameters (both clamped 0..1 since they are normalized weights)
+  weightDense: z.number().min(0).max(1).optional(),
+  weightFullText: z.number().min(0).max(1).optional(),
+  // MODEL parameters
+  modelProvider: z.string().optional(),
+  modelName: z.string().optional(),
+  filter: z.record(z.unknown()).optional(),
+});
+
+export type RetrievalInput = z.infer<typeof retrievalSchema>;

package/dist/dashboard-runtime/dashboard/src/services/api-client.ts

@@ -11,20 +11,32 @@ function fetchWithTimeout(
 ): Promise<Response> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
-  return fetch(url, { ...options, signal: controller.signal }).finally(() =>
-    clearTimeout(timer)
-  );
+  return fetch(url, {
+    credentials: "same-origin",
+    ...options,
+    signal: controller.signal,
+  }).finally(() => clearTimeout(timer));
 }
 
 class ApiClientError extends Error {
   code: string;
   status: number;
-
-  constructor(code: string, message: string, status: number) {
+  requestId?: string;
+  traceId?: string;
+
+  constructor(
+    code: string,
+    message: string,
+    status: number,
+    requestId?: string,
+    traceId?: string
+  ) {
     super(message);
     this.name = "ApiClientError";
     this.code = code;
     this.status = status;
+    this.requestId = requestId;
+    this.traceId = traceId;
   }
 }
 
@@ -40,25 +52,53 @@ async function handleResponse<T>(response: Response): Promise<T> {
   if (!response.ok) {
     let errorCode = HTTP_STATUS_CODE_MAP[response.status] ?? "UNKNOWN_ERROR";
     let errorMessage = `Request failed with status ${response.status}`;
+    let requestId: string | undefined;
+    const traceId = response.headers.get("x-trace-id") ?? undefined;
 
     try {
       const errorBody = await response.json();
       errorCode = errorBody.code ?? errorCode;
       errorMessage = errorBody.message ?? errorMessage;
+      requestId = errorBody.requestId;
     } catch {
       // Response body is not JSON, use defaults
     }
 
-    throw new ApiClientError(errorCode, errorMessage, response.status);
+    reportClientApiError({
+      code: errorCode,
+      message: errorMessage,
+      status: response.status,
+      requestId,
+      traceId,
+      url: response.url,
+    });
+    throw new ApiClientError(
+      errorCode,
+      errorMessage,
+      response.status,
+      requestId,
+      traceId
+    );
   }
 
   const body: ApiResponse<T> = await response.json();
 
   if (body.code !== "SUCCESS") {
+    const traceId = response.headers.get("x-trace-id") ?? undefined;
+    reportClientApiError({
+      code: body.code,
+      message: body.message ?? "Unknown error",
+      status: response.status,
+      requestId: body.requestId,
+      traceId,
+      url: response.url,
+    });
     throw new ApiClientError(
       body.code,
       body.message ?? "Unknown error",
-      response.status
+      response.status,
+      body.requestId,
+      traceId
     );
   }
 
@@ -77,11 +117,17 @@ function buildHeaders(contentType?: string): HeadersInit {
   return headers;
 }
 
-export async function apiGet<T>(path: string): Promise<T> {
-  const response = await fetchWithTimeout(buildUrl(path), {
-    method: "GET",
-    headers: buildHeaders("application/json"),
-  });
+export async function apiGet<T>(
+  path: string,
+  options: Pick<RequestInit, "cache"> = {},
+): Promise<T> {
+  const response = await requestWithClientLogging(path, () =>
+    fetchWithTimeout(buildUrl(path), {
+      method: "GET",
+      headers: buildHeaders("application/json"),
+      ...options,
+    })
+  );
   return handleResponse<T>(response);
 }
 
@@ -89,11 +135,13 @@ export async function apiPost<T>(
   path: string,
   body?: unknown
 ): Promise<T> {
-  const response = await fetchWithTimeout(buildUrl(path), {
-    method: "POST",
-    headers: buildHeaders("application/json"),
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  const response = await requestWithClientLogging(path, () =>
+    fetchWithTimeout(buildUrl(path), {
+      method: "POST",
+      headers: buildHeaders("application/json"),
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    })
+  );
   return handleResponse<T>(response);
 }
 
@@ -101,11 +149,13 @@ export async function apiPut<T>(
   path: string,
   body?: unknown
 ): Promise<T> {
-  const response = await fetchWithTimeout(buildUrl(path), {
-    method: "PUT",
-    headers: buildHeaders("application/json"),
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  const response = await requestWithClientLogging(path, () =>
+    fetchWithTimeout(buildUrl(path), {
+      method: "PUT",
+      headers: buildHeaders("application/json"),
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    })
+  );
   return handleResponse<T>(response);
 }
 
@@ -113,24 +163,79 @@ export async function apiDelete<T>(
   path: string,
   body?: unknown
 ): Promise<T> {
-  const response = await fetchWithTimeout(buildUrl(path), {
-    method: "DELETE",
-    headers: buildHeaders("application/json"),
-    body: body !== undefined ? JSON.stringify(body) : undefined,
-  });
+  const response = await requestWithClientLogging(path, () =>
+    fetchWithTimeout(buildUrl(path), {
+      method: "DELETE",
+      headers: buildHeaders("application/json"),
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    })
+  );
   return handleResponse<T>(response);
 }
 
 export async function apiUpload<T>(
   path: string,
-  formData: FormData
+  formData: FormData,
+  timeoutMs?: number
 ): Promise<T> {
-  const response = await fetchWithTimeout(buildUrl(path), {
-    method: "POST",
-    body: formData,
-    // Do not set Content-Type — browser sets multipart boundary automatically
-  });
+  const response = await requestWithClientLogging(path, () =>
+    fetchWithTimeout(buildUrl(path), {
+      method: "POST",
+      body: formData,
+      // Do not set Content-Type — browser sets multipart boundary automatically
+    }, timeoutMs)
+  );
   return handleResponse<T>(response);
 }
 
 export { ApiClientError };
+
+async function requestWithClientLogging(
+  path: string,
+  fn: () => Promise<Response>
+): Promise<Response> {
+  try {
+    return await fn();
+  } catch (error) {
+    reportClientApiError({
+      code: error instanceof DOMException && error.name === "AbortError"
+        ? "NETWORK_ERROR"
+        : "BROWSER_ERROR",
+      message: error instanceof Error ? error.message : String(error),
+      status: 0,
+      url: path,
+      name: error instanceof Error ? error.name : undefined,
+      stack: error instanceof Error ? error.stack : undefined,
+    });
+    throw error;
+  }
+}
+
+function reportClientApiError(payload: Record<string, unknown>): void {
+  if (typeof window === "undefined") return;
+  if (typeof payload.url === "string" && payload.url.includes("/api/v1/logs/client")) {
+    return;
+  }
+
+  try {
+    const body = JSON.stringify({
+      event: "browser.api_error",
+      ...payload,
+    });
+    if (navigator.sendBeacon) {
+      navigator.sendBeacon(
+        "/api/v1/logs/client",
+        new Blob([body], { type: "application/json" })
+      );
+      return;
+    }
+    void fetch("/api/v1/logs/client", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body,
+      keepalive: true,
+    });
+  } catch {
+    // Best-effort only.
+  }
+}

package/dist/dashboard-runtime/dashboard/src/services/auth.ts

@@ -0,0 +1,18 @@
+import { apiGet, apiPost } from "./api-client";
+
+export interface AuthStatus {
+  configured: boolean;
+  instanceName?: string;
+  region?: string;
+  activeInstance?: string | null;
+}
+
+export async function getAuthStatus(): Promise<AuthStatus> {
+  return apiGet<AuthStatus>("/api/v1/auth/status");
+}
+
+export async function importToken(
+  token: string
+): Promise<{ imported: boolean }> {
+  return apiPost<{ imported: boolean }>("/api/v1/auth/token", { token });
+}

package/dist/dashboard-runtime/dashboard/src/services/chunks.ts

@@ -0,0 +1,49 @@
+import type { Chunk } from "@/types/knowledge-base";
+import type { PaginatedData } from "@/types/api";
+import { apiGet, apiPut } from "./api-client";
+
+export async function listChunks(
+  knowledgeBaseName: string,
+  docId: string,
+  options?: { maxResults?: number; nextToken?: string; subspace?: string }
+): Promise<PaginatedData<Chunk>> {
+  const params = new URLSearchParams();
+  params.set("maxResults", String(options?.maxResults ?? 20));
+  if (options?.nextToken) {
+    params.set("nextToken", options.nextToken);
+  }
+  if (options?.subspace) {
+    params.set("subspace", options.subspace);
+  }
+  return apiGet<PaginatedData<Chunk>>(
+    `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/${encodeURIComponent(docId)}/chunks?${params.toString()}`
+  );
+}
+
+export interface UpdateChunkItem {
+  docId: string;
+  chunkId: number;
+  title?: string;
+  content?: string;
+  status?: "active" | "inactive";
+}
+
+export interface UpdateChunksResult {
+  updateDetails: Array<{
+    docId?: string;
+    ossKey?: string;
+    chunkId: number;
+    updateStatus: string;
+    failureReason?: string;
+  }>;
+}
+
+export async function updateChunks(
+  knowledgeBaseName: string,
+  chunks: UpdateChunkItem[]
+): Promise<UpdateChunksResult> {
+  return apiPut<UpdateChunksResult>(
+    `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/chunks`,
+    { chunks }
+  );
+}

package/dist/dashboard-runtime/dashboard/src/services/documents.ts

@@ -0,0 +1,208 @@
+import type { Document } from "@/types/knowledge-base";
+import type { PaginatedData } from "@/types/api";
+import { apiGet, apiPost, apiDelete, apiUpload } from "./api-client";
+
+export async function listDocuments(
+  knowledgeBaseName: string,
+  options?: { maxResults?: number; nextToken?: string; subspace?: string }
+): Promise<PaginatedData<Document>> {
+  const params = new URLSearchParams();
+  params.set("maxResults", String(options?.maxResults ?? 20));
+  if (options?.nextToken) {
+    params.set("nextToken", options.nextToken);
+  }
+  if (options?.subspace) {
+    params.set("subspace", options.subspace);
+  }
+  return apiGet<PaginatedData<Document>>(
+    `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents?${params.toString()}`
+  );
+}
+
+export async function getDocument(
+  knowledgeBaseName: string,
+  docId: string
+): Promise<Document> {
+  return apiGet<Document>(
+    `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/${encodeURIComponent(docId)}`
+  );
+}
+
+export interface AddDocumentsRequest {
+  knowledgeBaseName: string;
+  subspace?: string;
+  documents: Array<{
+    ossKey: string;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+export interface DocumentOperationResult {
+  docId?: string;
+  ossKey: string;
+  status: string;
+  failureReason?: string;
+}
+
+export async function addDocuments(
+  request: AddDocumentsRequest
+): Promise<{ documentDetails: DocumentOperationResult[] }> {
+  const { knowledgeBaseName, documents, ...rest } = request;
+  const url = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents`;
+
+  if (documents.length <= BATCH_SIZE) {
+    return apiPost<{ documentDetails: DocumentOperationResult[] }>(url, { documents, ...rest });
+  }
+
+  const allResults: DocumentOperationResult[] = [];
+  for (let i = 0; i < documents.length; i += BATCH_SIZE) {
+    const batch = documents.slice(i, i + BATCH_SIZE);
+    const resp = await apiPost<{ documentDetails: DocumentOperationResult[] }>(url, { documents: batch, ...rest });
+    allResults.push(...resp.documentDetails);
+  }
+  return { documentDetails: allResults };
+}
+
+export async function uploadDocuments(
+  knowledgeBaseName: string,
+  files: File[],
+  options?: { subspace?: string; metadata?: Record<string, unknown> }
+): Promise<{ documentDetails: DocumentOperationResult[] }> {
+  const formData = new FormData();
+
+  for (const file of files) {
+    formData.append("files", file);
+  }
+
+  if (options?.subspace) {
+    formData.append("subspace", options.subspace);
+  }
+
+  if (options?.metadata) {
+    formData.append("metadata", JSON.stringify(options.metadata));
+  }
+
+  return apiUpload<{ documentDetails: DocumentOperationResult[] }>(
+    `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/upload`,
+    formData
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Batched upload
+// ---------------------------------------------------------------------------
+
+// Server-side limit for documents per request across all batch endpoints.
+const BATCH_SIZE = 10;
+const UPLOAD_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per batch
+
+export interface BatchUploadProgress {
+  completedBatches: number;
+  totalBatches: number;
+  completedFiles: number;
+  totalFiles: number;
+  results: DocumentOperationResult[];
+  errors: string[];
+}
+
+/**
+ * Upload files in sequential batches of {@link BATCH_SIZE} to avoid
+ * hitting the client-side timeout on large folder uploads. Each batch is
+ * sent as a separate multipart request with an extended per-batch timeout.
+ *
+ * Progress is reported via the optional {@link options.onProgress} callback
+ * after every completed (or failed) batch.
+ */
+export async function uploadDocumentsBatched(
+  knowledgeBaseName: string,
+  files: File[],
+  options?: {
+    subspace?: string;
+    metadata?: Record<string, unknown>;
+    onProgress?: (progress: BatchUploadProgress) => void;
+  },
+): Promise<{ documentDetails: DocumentOperationResult[] }> {
+  const totalFiles = files.length;
+  const batches: File[][] = [];
+  for (let i = 0; i < totalFiles; i += BATCH_SIZE) {
+    batches.push(files.slice(i, i + BATCH_SIZE));
+  }
+
+  const allResults: DocumentOperationResult[] = [];
+  const allErrors: string[] = [];
+  const uploadPath = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents/upload`;
+
+  for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
+    const batch = batches[batchIdx];
+    const formData = new FormData();
+    for (const file of batch) {
+      formData.append("files", file);
+    }
+    if (options?.subspace) {
+      formData.append("subspace", options.subspace);
+    }
+    if (options?.metadata) {
+      formData.append("metadata", JSON.stringify(options.metadata));
+    }
+
+    try {
+      const resp = await apiUpload<{ documentDetails: DocumentOperationResult[] }>(
+        uploadPath,
+        formData,
+        UPLOAD_TIMEOUT_MS,
+      );
+      allResults.push(...resp.documentDetails);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      allErrors.push(`Batch ${batchIdx + 1}: ${msg}`);
+    }
+
+    options?.onProgress?.({
+      completedBatches: batchIdx + 1,
+      totalBatches: batches.length,
+      completedFiles: Math.min((batchIdx + 1) * BATCH_SIZE, totalFiles),
+      totalFiles,
+      results: allResults,
+      errors: allErrors,
+    });
+  }
+
+  // If every batch failed, throw so the caller sees a mutation error.
+  if (allResults.length === 0 && allErrors.length > 0) {
+    throw new Error(`All ${allErrors.length} batch(es) failed: ${allErrors[0]}`);
+  }
+
+  return { documentDetails: allResults };
+}
+
+export interface DeleteDocumentsRequest {
+  knowledgeBaseName: string;
+  subspace?: string;
+  documents: Array<{
+    docId?: string;
+    ossKey?: string;
+  }>;
+}
+
+export async function deleteDocuments(
+  request: DeleteDocumentsRequest,
+  onProgress?: (completed: number, total: number) => void,
+): Promise<{ documentDetails: DocumentOperationResult[] }> {
+  const { knowledgeBaseName, documents, ...rest } = request;
+  const url = `/api/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseName)}/documents`;
+
+  if (documents.length <= BATCH_SIZE) {
+    const result = await apiDelete<{ documentDetails: DocumentOperationResult[] }>(url, { documents, ...rest });
+    onProgress?.(documents.length, documents.length);
+    return result;
+  }
+
+  const allResults: DocumentOperationResult[] = [];
+  for (let i = 0; i < documents.length; i += BATCH_SIZE) {
+    const batch = documents.slice(i, i + BATCH_SIZE);
+    const resp = await apiDelete<{ documentDetails: DocumentOperationResult[] }>(url, { documents: batch, ...rest });
+    allResults.push(...resp.documentDetails);
+    onProgress?.(Math.min(i + BATCH_SIZE, documents.length), documents.length);
+  }
+  return { documentDetails: allResults };
+}