@tablestore/tablestore-agent-cli 0.1.8 → 0.2.0

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/chat/route.ts

@@ -0,0 +1,455 @@
+import { type NextRequest } from "next/server";
+
+import { chatCompletionStream } from "@/lib/server/llm-client";
+import { getProviderWithSecret } from "@/lib/server/llm-provider-store";
+import { rewriteQuery } from "@/lib/server/query-rewriter";
+import {
+  ensureApiLogContext,
+  errorResponse,
+  getApiLogContext,
+  requireClients,
+} from "@/lib/server/api-helpers";
+import { validateChatProjectContext } from "@/lib/server/chat-project-context";
+import { createLogger } from "@tablestore/tablestore-agent-shared";
+import { chatRequestSchema } from "@/schemas/llm-chat";
+import type {
+  ChatStreamEvent,
+  ChatRole,
+  ChatRagKnowledgeBase,
+  RetrievedChunk,
+  RetrievalGroup,
+} from "@/types/llm-chat";
+import type { RetrievalResult } from "@/types/retrieval";
+
+// Default aggregate cap when the client omits `rag.topK`.
+const DEFAULT_AGGREGATE_TOP_K = 20;
+
+// Keep the edge runtime disabled so Node `crypto` + file IO (provider store)
+// keep working; a streaming Node runtime is fine for SSE.
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const DEFAULT_RAG_SYSTEM_PROMPT =
+  "你是一个基于知识库检索结果回答问题的助手。请严格参考下面的「检索结果」回答用户问题；若检索结果未涵盖相关信息，请如实说明未在知识库中找到，不要编造。回答时可以在末尾用 `[1]` `[2]` 等编号标注引用来源。";
+
+// Maximum number of history messages (excluding system) forwarded to the LLM.
+// Matches the plan's simple "keep last 20 turns" policy; token-based trimming
+// can land later when we wire up `tiktoken`.
+const MAX_HISTORY_MESSAGES = 20;
+const chatLogger = createLogger("dashboard.api.llm");
+
+/**
+ * POST /api/v1/llm/chat
+ *
+ * Server-sent events. Each frame is a single `data: <json>\n\n` line whose
+ * payload is a `ChatStreamEvent`. The route orchestrates:
+ *
+ *   1. (optional) RAG retrieval against a knowledge base.
+ *   2. Building the final system prompt from user + retrieved chunks.
+ *   3. Proxying the upstream `/chat/completions` stream, relaying deltas as
+ *      `content.delta` / `reasoning.delta` events.
+ *
+ * Errors are streamed as `{"type":"error",...}` frames rather than HTTP
+ * errors after headers have been sent; pre-flight validation failures still
+ * use a regular 4xx response because the body has not started.
+ */
+export async function POST(request: NextRequest) {
+  ensureApiLogContext(request);
+  const raw = await request.json().catch(() => null);
+  const parsed = chatRequestSchema.safeParse(raw);
+  if (!parsed.success) {
+    return jsonError(
+      400,
+      "VALIDATION_ERROR",
+      parsed.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join("; "),
+    );
+  }
+
+  const body = parsed.data;
+  const activeInstanceProvided =
+    raw !== null &&
+    typeof raw === "object" &&
+    Object.prototype.hasOwnProperty.call(raw, "activeInstance");
+  const lastUser = [...body.messages].reverse().find((m) => m.role === "user");
+  if (!lastUser) {
+    return jsonError(
+      400,
+      "VALIDATION_ERROR",
+      "messages must contain at least one user turn",
+    );
+  }
+
+  const provider = await getProviderWithSecret(body.providerId).catch(
+    () => null,
+  );
+  if (!provider) {
+    return jsonError(
+      404,
+      "NOT_FOUND",
+      `Provider ${body.providerId} not found or cannot be decrypted`,
+    );
+  }
+
+  // RAG path requires Tablestore credentials; only resolve them when needed
+  // so pure LLM usage (no `rag`) does not hit the auth layer.
+  type ResolvedKbClient = Awaited<ReturnType<typeof resolveKbClient>>;
+  let kbClient: ResolvedKbClient | null = null;
+  if (body.rag) {
+    const projectContext = validateChatProjectContext(
+      request,
+      activeInstanceProvided ? body.activeInstance ?? null : undefined,
+    );
+    if (!projectContext.ok) {
+      return jsonError(
+        409,
+        "PROJECT_CONTEXT_CHANGED",
+        projectContext.message,
+      );
+    }
+    kbClient = await resolveKbClient(request);
+    if (!kbClient.ok) {
+      return jsonError(
+        kbClient.status,
+        kbClient.code,
+        kbClient.message,
+      );
+    }
+  }
+
+  const upstreamAbort = new AbortController();
+  const cleanup = () => {
+    try {
+      upstreamAbort.abort();
+    } catch {
+      // noop
+    }
+  };
+  // If the client disconnects mid-stream, propagate cancellation upstream so
+  // we stop paying for tokens we'll never deliver.
+  request.signal.addEventListener("abort", cleanup, { once: true });
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      const startedAt = Date.now();
+      const logContext = getApiLogContext();
+      const emit = (event: ChatStreamEvent) => {
+        controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
+      };
+
+      let closed = false;
+      const close = () => {
+        if (closed) return;
+        closed = true;
+        try {
+          controller.close();
+        } catch {
+          // Controller may already be closed if the client disconnected.
+        }
+        request.signal.removeEventListener("abort", cleanup);
+      };
+
+      try {
+        // ---- RAG retrieval ----
+        let chunks: RetrievedChunk[] = [];
+        let groupsForPrompt: RetrievalGroup[] = [];
+        if (body.rag && kbClient?.ok) {
+          // Decide retrieval query: on multi-turn (>=2 non-system messages),
+          // condense the history into a standalone question; otherwise keep
+          // the raw user input.
+          const nonSystem = body.messages.filter((m) => m.role !== "system");
+          const shouldRewrite = nonSystem.length >= 2;
+
+          let retrievalQuery = lastUser.content;
+          let rewritten = false;
+          if (shouldRewrite) {
+            try {
+              // Drop the final user turn; it is passed as the "question"
+              // argument to the rewriter separately.
+              const historyForRewrite = nonSystem.slice(0, -1);
+              const rewrittenQuery = await rewriteQuery(
+                provider,
+                body.model,
+                historyForRewrite,
+                lastUser.content,
+                upstreamAbort.signal,
+              );
+              if (rewrittenQuery && rewrittenQuery !== lastUser.content) {
+                retrievalQuery = rewrittenQuery;
+                rewritten = true;
+              }
+            } catch (err) {
+              emit({
+                type: "query.fallback",
+                original: lastUser.content,
+                reason: err instanceof Error ? err.message : String(err),
+              });
+            }
+          }
+
+          // Always emit the final query so the UI knows exactly what ran
+          // against the KB; `original === query` means no rewrite happened.
+          emit({
+            type: "query.rewritten",
+            query: retrievalQuery,
+            original: lastUser.content,
+          });
+          void rewritten;
+
+          emit({ type: "retrieval.start" });
+          const { aggregated, groups } = await retrieveFromAllKbs(
+            kbClient.client,
+            body.rag.knowledgeBases,
+            retrievalQuery,
+            body.rag.topK ?? DEFAULT_AGGREGATE_TOP_K,
+          );
+          chunks = aggregated;
+          groupsForPrompt = groups;
+          emit({
+            type: "retrieval.done",
+            chunks: aggregated,
+            byKnowledgeBase: groups,
+          });
+        }
+
+        // ---- Build final messages ----
+        const finalMessages = buildFinalMessages(
+          body.systemPrompt ?? "",
+          chunks,
+          groupsForPrompt,
+          body.messages,
+        );
+
+        // ---- Stream upstream completion ----
+        const upstream = await chatCompletionStream(provider, {
+          model: body.model,
+          messages: finalMessages,
+          temperature: body.temperature,
+          signal: upstreamAbort.signal,
+        });
+
+        const reader = upstream.getReader();
+        while (true) {
+          const { value, done } = await reader.read();
+          if (done) break;
+          emit(value);
+          if (value.type === "done" || value.type === "error") {
+            break;
+          }
+        }
+        chatLogger.info({
+          event: "api.stream_response",
+          message: "LLM chat stream completed",
+          dashboardSessionId: logContext?.dashboardSessionId,
+          traceId: logContext?.traceId,
+          durationMs: Date.now() - startedAt,
+          details: {
+            path: logContext?.path,
+            status: 200,
+            code: "SUCCESS",
+            ragEnabled: Boolean(body.rag),
+          },
+        });
+        close();
+      } catch (err) {
+        chatLogger.error({
+          event: "api.stream_error",
+          message: err instanceof Error ? err.message : String(err),
+          dashboardSessionId: logContext?.dashboardSessionId,
+          traceId: logContext?.traceId,
+          durationMs: Date.now() - startedAt,
+          error: err,
+          details: {
+            path: logContext?.path,
+            code: "INTERNAL_SERVER_ERROR",
+            ragEnabled: Boolean(body.rag),
+          },
+        });
+        emit({
+          type: "error",
+          code: "INTERNAL_SERVER_ERROR",
+          message: err instanceof Error ? err.message : String(err),
+        });
+        close();
+      }
+    },
+    cancel() {
+      cleanup();
+    },
+  });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      "Content-Type": "text/event-stream; charset=utf-8",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+      // Disable nginx-style buffering proxies so events reach the browser
+      // as they are produced.
+      "X-Accel-Buffering": "no",
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function jsonError(status: number, code: string, message: string): Response {
+  return errorResponse(code, message, status);
+}
+
+/**
+ * Resolve the knowledge base client for the current session. Returns either
+ * a ready-to-use client or a structured error descriptor so the caller can
+ * decide whether to fail the whole request or only skip RAG.
+ */
+async function resolveKbClient(request: NextRequest): Promise<
+  | { ok: true; client: import("@tablestore/tablestore-agent-sdk").KnowledgeBaseClient }
+  | { ok: false; status: number; code: string; message: string }
+> {
+  const resolved = requireClients(request);
+  if (resolved instanceof Response) {
+    // requireClients returns a NextResponse with the envelope already built;
+    // extract the code/message so we can surface them uniformly.
+    const body = await resolved.json().catch(() => null);
+    return {
+      ok: false,
+      status: resolved.status,
+      code: body?.code ?? "UNAUTHORIZED",
+      message: body?.message ?? "Failed to resolve credentials",
+    };
+  }
+  return { ok: true, client: resolved.kb };
+}
+
+/**
+ * Compose the system prompt and cap the history window. The retrieval chunks
+ * are appended *after* the user-supplied prompt so user instructions take
+ * priority, and each chunk is tagged with a bracketed index the model can
+ * cite back. The header mentions the KB count when multiple KBs were queried
+ * so the model can reason about source diversity.
+ */
+function buildFinalMessages(
+  userSystemPrompt: string,
+  chunks: RetrievedChunk[],
+  groups: RetrievalGroup[],
+  history: Array<{ role: ChatRole; content: string }>,
+): Array<{ role: ChatRole; content: string }> {
+  const preamble = userSystemPrompt.trim() || DEFAULT_RAG_SYSTEM_PROMPT;
+  const successfulKbCount = groups.filter((g) => !g.error).length;
+  const header = successfulKbCount > 1
+    ? `检索结果（共 ${chunks.length} 条，来自 ${successfulKbCount} 个知识库）：`
+    : `检索结果（共 ${chunks.length} 条）：`;
+  const contextBlock = chunks.length
+    ? `\n\n${header}\n${chunks
+        .map((c, i) => {
+          const src = c.knowledgeBaseName ? ` (${c.knowledgeBaseName})` : "";
+          return `[${i + 1}]${src} ${truncate(c.content, 1200)}`;
+        })
+        .join("\n\n")}`
+    : "";
+
+  // Strip any `system` messages the client sent — we own the system turn.
+  const nonSystem = history.filter((m) => m.role !== "system");
+  const clipped =
+    nonSystem.length > MAX_HISTORY_MESSAGES
+      ? nonSystem.slice(-MAX_HISTORY_MESSAGES)
+      : nonSystem;
+
+  return [
+    { role: "system", content: preamble + contextBlock },
+    ...clipped,
+  ];
+}
+
+function truncate(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}…`;
+}
+
+/**
+ * Fan out the retrieval query to every mounted KB in parallel. Individual
+ * failures are captured per-group so one broken KB never breaks the whole
+ * turn; the aggregate list is the union of successful groups sorted by score
+ * and clipped to `aggregateTopK`.
+ */
+async function retrieveFromAllKbs(
+  client: import("@tablestore/tablestore-agent-sdk").KnowledgeBaseClient,
+  mounts: ChatRagKnowledgeBase[],
+  retrievalQuery: string,
+  aggregateTopK: number,
+): Promise<{ aggregated: RetrievedChunk[]; groups: RetrievalGroup[] }> {
+  const settled = await Promise.allSettled(
+    mounts.map(async (mount) => {
+      const retrievalConfiguration = buildKbRetrievalConfiguration(mount);
+      const resp = await client.retrieve({
+        knowledgeBaseName: mount.knowledgeBaseName,
+        retrievalQuery: { type: "TEXT", text: retrievalQuery },
+        ...(mount.subspace?.length ? { subspace: mount.subspace } : {}),
+        ...(retrievalConfiguration ? { retrievalConfiguration } : {}),
+      });
+      if (resp.code !== "SUCCESS") {
+        throw new Error(resp.message ?? `Retrieval failed (${resp.code})`);
+      }
+      const results =
+        (resp.data as { retrievalResults?: RetrievalResult[] })
+          ?.retrievalResults ?? [];
+      return results.map<RetrievedChunk>((r) => ({
+        ...r,
+        knowledgeBaseName: mount.knowledgeBaseName,
+      }));
+    }),
+  );
+
+  const groups: RetrievalGroup[] = settled.map((outcome, idx) => {
+    const mount = mounts[idx];
+    if (outcome.status === "fulfilled") {
+      return { knowledgeBaseName: mount.knowledgeBaseName, chunks: outcome.value };
+    }
+    const reason = outcome.reason;
+    return {
+      knowledgeBaseName: mount.knowledgeBaseName,
+      chunks: [],
+      error: reason instanceof Error ? reason.message : String(reason),
+    };
+  });
+
+  const aggregated = groups
+    .flatMap((g) => g.chunks)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, aggregateTopK);
+
+  return { aggregated, groups };
+}
+
+/**
+ * Merge the per-KB user-provided retrieval configuration with the mount's
+ * `topK`. The `topK` shortcut fills in both numberOfResults hooks so users
+ * don't have to duplicate it on dense/fulltext configs.
+ */
+function buildKbRetrievalConfiguration(
+  mount: ChatRagKnowledgeBase,
+): Record<string, unknown> | undefined {
+  const cfg: Record<string, unknown> = { ...(mount.retrievalConfiguration ?? {}) };
+  if (typeof mount.topK === "number") {
+    const dense = (cfg.denseVectorSearchConfiguration ?? {}) as Record<string, unknown>;
+    const fulltext = (cfg.fullTextSearchConfiguration ?? {}) as Record<string, unknown>;
+    const rerank = (cfg.rerankingConfiguration ?? {}) as Record<string, unknown>;
+    cfg.denseVectorSearchConfiguration = {
+      numberOfResults: mount.topK,
+      ...dense,
+    };
+    cfg.fullTextSearchConfiguration = {
+      numberOfResults: mount.topK,
+      ...fulltext,
+    };
+    cfg.rerankingConfiguration = {
+      numberOfResults: mount.topK,
+      ...rerank,
+    };
+  }
+  return Object.keys(cfg).length ? cfg : undefined;
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/providers/[id]/models/route.ts

@@ -0,0 +1,46 @@
+import { type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+import {
+  ensureApiLogContext,
+  errorResponse,
+  handleApiError,
+  successResponse,
+} from "@/lib/server/api-helpers";
+import { listModels } from "@/lib/server/llm-client";
+import { getProviderWithSecret } from "@/lib/server/llm-provider-store";
+
+interface RouteContext {
+  params: Promise<{ id: string }>;
+}
+
+/**
+ * GET /api/v1/llm/providers/:id/models
+ *
+ * Calls the upstream `/models` endpoint and relays the list. Failures surface
+ * as `NETWORK_ERROR` so the UI can show them inline next to the dropdown.
+ */
+export async function GET(_request: NextRequest, ctx: RouteContext) {
+  ensureApiLogContext(_request);
+  try {
+    const { id } = await ctx.params;
+    const provider = await getProviderWithSecret(id);
+    if (!provider) {
+      return errorResponse("NOT_FOUND", `Provider ${id} not found`, 404);
+    }
+    try {
+      const models = await listModels(provider);
+      return successResponse({ models });
+    } catch (err) {
+      return errorResponse(
+        "NETWORK_ERROR",
+        err instanceof Error ? err.message : String(err),
+        502,
+      );
+    }
+  } catch (err) {
+    return handleApiError(err);
+  }
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/providers/[id]/route.ts

@@ -0,0 +1,83 @@
+import { type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+import {
+  ensureApiLogContext,
+  errorResponse,
+  handleApiError,
+  successResponse,
+} from "@/lib/server/api-helpers";
+import {
+  deleteProvider,
+  getProvider,
+  updateProvider,
+} from "@/lib/server/llm-provider-store";
+import { updateLLMProviderSchema } from "@/schemas/llm-provider";
+
+interface RouteContext {
+  params: Promise<{ id: string }>;
+}
+
+export async function GET(_request: NextRequest, ctx: RouteContext) {
+  ensureApiLogContext(_request);
+  try {
+    const { id } = await ctx.params;
+    const provider = await getProvider(id);
+    if (!provider) {
+      return errorResponse("NOT_FOUND", `Provider ${id} not found`, 404);
+    }
+    return successResponse({ provider });
+  } catch (err) {
+    return handleApiError(err);
+  }
+}
+
+export async function PUT(request: NextRequest, ctx: RouteContext) {
+  ensureApiLogContext(request);
+  try {
+    const { id } = await ctx.params;
+    const raw = await request.json().catch(() => null);
+    const parsed = updateLLMProviderSchema.safeParse(raw);
+    if (!parsed.success) {
+      return errorResponse(
+        "VALIDATION_ERROR",
+        parsed.error.issues
+          .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+          .join("; "),
+        400,
+      );
+    }
+
+    if (parsed.data.type && parsed.data.type !== "openai-compatible") {
+      return errorResponse(
+        "VALIDATION_ERROR",
+        `Provider type "${parsed.data.type}" is not supported yet`,
+        400,
+      );
+    }
+
+    const updated = await updateProvider(id, parsed.data);
+    if (!updated) {
+      return errorResponse("NOT_FOUND", `Provider ${id} not found`, 404);
+    }
+    return successResponse({ provider: updated });
+  } catch (err) {
+    return handleApiError(err);
+  }
+}
+
+export async function DELETE(_request: NextRequest, ctx: RouteContext) {
+  ensureApiLogContext(_request);
+  try {
+    const { id } = await ctx.params;
+    const ok = await deleteProvider(id);
+    if (!ok) {
+      return errorResponse("NOT_FOUND", `Provider ${id} not found`, 404);
+    }
+    return successResponse({ deleted: true });
+  } catch (err) {
+    return handleApiError(err);
+  }
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/providers/[id]/test/route.ts

@@ -0,0 +1,40 @@
+import { type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+import {
+  ensureApiLogContext,
+  errorResponse,
+  handleApiError,
+  successResponse,
+} from "@/lib/server/api-helpers";
+import { testConnectivity } from "@/lib/server/llm-client";
+import { getProviderWithSecret } from "@/lib/server/llm-provider-store";
+
+interface RouteContext {
+  params: Promise<{ id: string }>;
+}
+
+/**
+ * POST /api/v1/llm/providers/:id/test
+ *
+ * Synchronously exercises the upstream `/models` endpoint and returns a
+ * structured `ConnectivityResult`. The handler never rejects on upstream
+ * failure: failures are reported inside the envelope so the UI can render
+ * them alongside a green/red status dot.
+ */
+export async function POST(_request: NextRequest, ctx: RouteContext) {
+  ensureApiLogContext(_request);
+  try {
+    const { id } = await ctx.params;
+    const provider = await getProviderWithSecret(id);
+    if (!provider) {
+      return errorResponse("NOT_FOUND", `Provider ${id} not found`, 404);
+    }
+    const result = await testConnectivity(provider);
+    return successResponse({ result });
+  } catch (err) {
+    return handleApiError(err);
+  }
+}

package/dist/dashboard-runtime/dashboard/src/app/api/v1/llm/providers/route.ts

@@ -0,0 +1,70 @@
+import { type NextRequest } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+import {
+  ensureApiLogContext,
+  errorResponse,
+  handleApiError,
+  successResponse,
+} from "@/lib/server/api-helpers";
+import {
+  createProvider,
+  listProviders,
+} from "@/lib/server/llm-provider-store";
+import { createLLMProviderSchema } from "@/schemas/llm-provider";
+
+/**
+ * GET /api/v1/llm/providers
+ *
+ * Returns the public view (no secrets) of all stored LLM providers. The list
+ * is local to the Dashboard host — it is not persisted in Tablestore and
+ * does not require Tablestore credentials.
+ */
+export async function GET(request: NextRequest) {
+  ensureApiLogContext(request);
+  try {
+    const providers = await listProviders();
+    return successResponse({ providers });
+  } catch (err) {
+    return handleApiError(err);
+  }
+}
+
+/**
+ * POST /api/v1/llm/providers
+ *
+ * Body: CreateLLMProviderInput (plaintext apiKey). The apiKey is encrypted
+ * before it touches disk.
+ */
+export async function POST(request: NextRequest) {
+  ensureApiLogContext(request);
+  try {
+    const raw = await request.json().catch(() => null);
+    const parsed = createLLMProviderSchema.safeParse(raw);
+    if (!parsed.success) {
+      return errorResponse(
+        "VALIDATION_ERROR",
+        parsed.error.issues
+          .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+          .join("; "),
+        400,
+      );
+    }
+
+    // `type` is locked to openai-compatible until the other adapters land.
+    if (parsed.data.type !== "openai-compatible") {
+      return errorResponse(
+        "VALIDATION_ERROR",
+        `Provider type "${parsed.data.type}" is not supported yet`,
+        400,
+      );
+    }
+
+    const created = await createProvider(parsed.data);
+    return successResponse({ provider: created }, 201);
+  } catch (err) {
+    return handleApiError(err);
+  }
+}