@tablestore/tablestore-agent-cli 0.3.1 → 0.4.1

package/dist/dashboard-runtime/dashboard/src/lib/wiki-metadata-limits.ts

@@ -0,0 +1,133 @@
+import type {
+  WikiEvidence,
+  WikiRetrievalError,
+  WikiRetrievalGroup,
+} from "@/types/llm-chat";
+
+export const MAX_WIKI_METADATA_ID_CHARS = 256;
+export const MAX_WIKI_METADATA_PATH_CHARS = 1_024;
+export const MAX_WIKI_METADATA_NAME_CHARS = 256;
+export const MAX_WIKI_METADATA_TITLE_CHARS = 512;
+export const MAX_WIKI_METADATA_TYPE_CHARS = 128;
+export const MAX_WIKI_METADATA_DESCRIPTION_CHARS = 2_048;
+export const MAX_WIKI_METADATA_SOURCE_CHARS = 1_024;
+export const MAX_WIKI_ERROR_CODE_CHARS = 128;
+export const MAX_WIKI_ERROR_MESSAGE_CHARS = 1_024;
+export const MAX_WIKI_ERROR_PATH_CHARS = 1_024;
+export const MAX_WIKI_SOURCES = 8;
+export const MAX_WIKI_ERRORS = 4;
+export const MAX_WIKI_EVIDENCE = 6;
+export const MAX_WIKI_GROUPS = 10;
+
+export function normalizeRequiredWikiMetadata(
+  value: unknown,
+): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+export function truncateWikiMetadata(
+  value: string,
+  maxCodePoints: number,
+): string {
+  const codePoints = Array.from(value);
+  if (codePoints.length <= maxCodePoints) return value;
+  if (maxCodePoints <= 0) return "";
+  return `${codePoints.slice(0, maxCodePoints - 1).join("")}…`;
+}
+
+export function clampWikiEvidence(value: WikiEvidence): WikiEvidence {
+  return {
+    reference: value.reference,
+    wikiName: truncateWikiMetadata(
+      value.wikiName,
+      MAX_WIKI_METADATA_NAME_CHARS,
+    ),
+    path: truncateWikiMetadata(value.path, MAX_WIKI_METADATA_PATH_CHARS),
+    ...(value.title === undefined
+      ? {}
+      : {
+          title: truncateWikiMetadata(
+            value.title,
+            MAX_WIKI_METADATA_TITLE_CHARS,
+          ),
+        }),
+    ...(value.type === undefined
+      ? {}
+      : {
+          type: truncateWikiMetadata(value.type, MAX_WIKI_METADATA_TYPE_CHARS),
+        }),
+    ...(value.description === undefined
+      ? {}
+      : {
+          description: truncateWikiMetadata(
+            value.description,
+            MAX_WIKI_METADATA_DESCRIPTION_CHARS,
+          ),
+        }),
+    ...(value.score === undefined ? {} : { score: value.score }),
+    ...(value.sources === undefined
+      ? {}
+      : {
+          sources: value.sources
+            .slice(0, MAX_WIKI_SOURCES)
+            .map((source) =>
+              truncateWikiMetadata(source, MAX_WIKI_METADATA_SOURCE_CHARS),
+            ),
+        }),
+    truncated: value.truncated,
+    injectedChars: value.injectedChars,
+  };
+}
+
+export function clampWikiRetrievalError(
+  value: WikiRetrievalError,
+): WikiRetrievalError {
+  return {
+    code: truncateWikiMetadata(value.code, MAX_WIKI_ERROR_CODE_CHARS),
+    message: truncateWikiMetadata(value.message, MAX_WIKI_ERROR_MESSAGE_CHARS),
+    ...(value.requestId === undefined
+      ? {}
+      : {
+          requestId: truncateWikiMetadata(
+            value.requestId,
+            MAX_WIKI_METADATA_ID_CHARS,
+          ),
+        }),
+    ...(value.httpStatus === undefined ? {} : { httpStatus: value.httpStatus }),
+    stage: value.stage,
+    ...(value.path === undefined
+      ? {}
+      : {
+          path: truncateWikiMetadata(value.path, MAX_WIKI_ERROR_PATH_CHARS),
+        }),
+  };
+}
+
+export function clampWikiRetrievalGroup(
+  value: WikiRetrievalGroup,
+): WikiRetrievalGroup {
+  return {
+    wikiName: truncateWikiMetadata(
+      value.wikiName,
+      MAX_WIKI_METADATA_NAME_CHARS,
+    ),
+    pages: value.pages.slice(0, MAX_WIKI_EVIDENCE).map(clampWikiEvidence),
+    ...(value.errors === undefined
+      ? {}
+      : {
+          errors: value.errors
+            .slice(0, MAX_WIKI_ERRORS)
+            .map(clampWikiRetrievalError),
+        }),
+  };
+}
+
+export function clampWikiRetrievalGroups(
+  values: ReadonlyArray<WikiRetrievalGroup>,
+): WikiRetrievalGroup[] {
+  return values
+    .slice(0, MAX_WIKI_GROUPS)
+    .map((group) => clampWikiRetrievalGroup(group));
+}

package/dist/dashboard-runtime/dashboard/src/lib/wiki-page-tree.ts

@@ -0,0 +1,153 @@
+import type { WikiPage } from "@/types/wiki";
+
+export interface WikiTreeSourceFile {
+  rel: string;
+  originalPath: string;
+  size: number;
+}
+
+export interface WikiTreeFile extends WikiTreeSourceFile {
+  type: "file";
+  name: string;
+}
+
+export interface WikiTreeDir {
+  type: "dir";
+  name: string;
+  rel: string;
+  children: WikiTreeNode[];
+}
+
+export type WikiTreeNode = WikiTreeDir | WikiTreeFile;
+
+export interface VisibleWikiTreeRow {
+  node: WikiTreeNode;
+  depth: number;
+}
+
+export function wikiDisplayPath(path: string): string {
+  return path.startsWith("/wiki/")
+    ? path.slice("/wiki/".length)
+    : path.replace(/^\/+/, "");
+}
+
+export function toWikiTreeFile(
+  page: Pick<WikiPage, "path">,
+): WikiTreeSourceFile {
+  return {
+    rel: wikiDisplayPath(page.path),
+    originalPath: page.path,
+    size: 0,
+  };
+}
+
+export function mergeWikiPages(
+  ...groups: ReadonlyArray<readonly WikiPage[]>
+): WikiPage[] {
+  const merged: WikiPage[] = [];
+  const seen = new Set<string>();
+  for (const group of groups) {
+    for (const page of group) {
+      if (seen.has(page.path)) continue;
+      seen.add(page.path);
+      merged.push(page);
+    }
+  }
+  return merged;
+}
+
+function sortChildren(nodes: WikiTreeNode[]): void {
+  nodes.sort((left, right) => {
+    if (left.type !== right.type) return left.type === "dir" ? -1 : 1;
+    return left.name.localeCompare(right.name);
+  });
+  for (const node of nodes) {
+    if (node.type === "dir") sortChildren(node.children);
+  }
+}
+
+export function buildWikiPageTree(pages: readonly WikiPage[]): WikiTreeDir {
+  const root: WikiTreeDir = {
+    type: "dir",
+    name: "",
+    rel: "",
+    children: [],
+  };
+
+  for (const page of mergeWikiPages(pages)) {
+    const file = toWikiTreeFile(page);
+    const parts = file.rel.split("/").filter(Boolean);
+    if (parts.length === 0) continue;
+
+    let cursor = root;
+    for (let index = 0; index < parts.length - 1; index += 1) {
+      const name = parts[index]!;
+      const rel = parts.slice(0, index + 1).join("/");
+      let directory = cursor.children.find(
+        (node): node is WikiTreeDir =>
+          node.type === "dir" && node.name === name,
+      );
+      if (!directory) {
+        directory = { type: "dir", name, rel, children: [] };
+        cursor.children.push(directory);
+      }
+      cursor = directory;
+    }
+
+    const name = parts.at(-1)!;
+    if (
+      !cursor.children.some(
+        (node) => node.type === "file" && node.name === name,
+      )
+    ) {
+      cursor.children.push({ type: "file", name, ...file });
+    }
+  }
+
+  sortChildren(root.children);
+  return root;
+}
+
+export function flattenWikiPageTree(
+  root: WikiTreeDir,
+  collapsed: ReadonlySet<string>,
+): VisibleWikiTreeRow[] {
+  const rows: VisibleWikiTreeRow[] = [];
+  const visit = (nodes: readonly WikiTreeNode[], depth: number) => {
+    for (const node of nodes) {
+      rows.push({ node, depth });
+      if (node.type === "dir" && !collapsed.has(node.rel)) {
+        visit(node.children, depth + 1);
+      }
+    }
+  };
+  visit(root.children, 0);
+  return rows;
+}
+
+export function ancestorDirectories(path: string): string[] {
+  const parts = wikiDisplayPath(path).split("/").filter(Boolean).slice(0, -1);
+  return parts.map((_, index) => parts.slice(0, index + 1).join("/"));
+}
+
+export function toggleWikiDirectory(
+  collapsed: ReadonlySet<string>,
+  directory: string,
+): ReadonlySet<string> {
+  const next = new Set(collapsed);
+  if (next.has(directory)) next.delete(directory);
+  else next.add(directory);
+  return next;
+}
+
+export function expandWikiPageAncestors(
+  collapsed: ReadonlySet<string>,
+  pagePath: string,
+): ReadonlySet<string> {
+  const next = new Set(collapsed);
+  let changed = false;
+  for (const directory of ancestorDirectories(pagePath)) {
+    changed = next.delete(directory) || changed;
+  }
+  return changed ? next : collapsed;
+}

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

@@ -1,6 +1,10 @@
 import { z } from "zod";
 
-import { FILEMEM_DEFAULT_RUN_ID } from "@/lib/memory-storage-mode";
+import { normalizeFileMemoryStoreName } from "@/lib/file-memory-core";
+import {
+  FILEMEM_DEFAULT_RUN_ID,
+  STORAGE_MODE_VALUES,
+} from "@/lib/memory-storage-mode";
 
 export const chatRoleSchema = z.enum(["user", "assistant", "system"]);
 
@@ -25,6 +29,7 @@ export const chatRagSchema = z.object({
 // 客户端不允许显式发 `*`——通配符仅由服务端在 SearchMemories 调用前注入。
 const nonWildcardId = z
   .string()
+  .trim()
   .min(1)
   .refine((v) => v !== "*", {
     message: "wildcard '*' is not allowed on the wire; the server applies it",
@@ -46,6 +51,7 @@ const browserFileContextSchema = z.object({
       z.object({
         rel: z.string().min(1).max(512),
         size: z.number().int().nonnegative(),
+        sha256: z.string().min(1).max(256).optional(),
       }),
     )
     .max(300),
@@ -61,10 +67,10 @@ const browserFileContextSchema = z.object({
   cache: memoryFilesCacheSchema,
 });
 
-export const chatMemorySchema = z
+const chatMemoryWireSchema = z
   .object({
     memoryStoreName: z.string().min(1),
-    storageMode: z.enum(["ots", "file+ots", "filemem"]).optional(),
+    storageMode: z.enum(STORAGE_MODE_VALUES).optional(),
     scope: z.object({
       appId: nonWildcardId,
       tenantId: nonWildcardId,
@@ -74,34 +80,131 @@ export const chatMemorySchema = z
     topK: z.number().int().min(1).max(50).optional(),
     autoSave: z.boolean().optional(),
     turnId: z.string().min(1).optional(),
-    // 缺省 "search"（语义检索）；"local" 走浏览器文件 API 缓存与词法检索。
+    // 缺省 "search"（语义检索）；"local" 由 Chat BFF 走 Item API + 有界 SHA cache。
     retrievalMode: z.enum(["search", "local"]).optional(),
     fileContext: browserFileContextSchema.optional(),
   })
-  .transform((memory) =>
-    memory.storageMode === "filemem"
-      ? {
-          ...memory,
-          scope: { ...memory.scope, runId: FILEMEM_DEFAULT_RUN_ID },
-          retrievalMode: "local" as const,
-        }
-      : memory,
-  );
+  .superRefine((memory, ctx) => {
+    if (memory.storageMode === "filemem" && !memory.memoryStoreName.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["memoryStoreName"],
+        message: "File Memory store name cannot be blank",
+      });
+    }
+  });
+
+type ChatMemoryWire = z.infer<typeof chatMemoryWireSchema>;
+
+function normalizeChatMemory(memory: ChatMemoryWire) {
+  return memory.storageMode === "filemem"
+    ? {
+        ...memory,
+        memoryStoreName: normalizeFileMemoryStoreName(memory.memoryStoreName),
+        scope: { ...memory.scope, runId: FILEMEM_DEFAULT_RUN_ID },
+        retrievalMode: "local" as const,
+      }
+    : memory;
+}
+
+export const chatMemorySchema =
+  chatMemoryWireSchema.transform(normalizeChatMemory);
+
+const chatWikiSchema = z
+  .object({
+    memoryStoreName: z.string().trim().min(1),
+    scope: z
+      .object({
+        appId: nonWildcardId,
+        tenantId: nonWildcardId,
+        agentId: nonWildcardId,
+        runId: nonWildcardId,
+      })
+      .strict(),
+    topK: z.number().int().min(1).max(10),
+  })
+  .strict();
 
 /**
  * Server-side validation for the chat endpoint payload. The last message must
  * be from the user; this rule is enforced in the route handler rather than
  * 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),
-  systemPrompt: z.string().max(8_000).optional(),
-  temperature: z.number().min(0).max(2).optional(),
-  rag: chatRagSchema.optional(),
-  memory: chatMemorySchema.optional(),
-});
+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),
+    systemPrompt: z.string().max(8_000).optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    rag: chatRagSchema.optional(),
+    memory: chatMemoryWireSchema.optional(),
+    wiki: chatWikiSchema.optional(),
+  })
+  .strict()
+  .superRefine((request, ctx) => {
+    if (!request.wiki) return;
+    if (!request.memory) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["wiki"],
+        message: "Wiki binding requires a Memory binding",
+      });
+      return;
+    }
+    if (!request.memory.storageMode) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["memory", "storageMode"],
+        message: "Wiki binding requires an explicit Memory storage mode",
+      });
+      return;
+    }
+
+    const isFileMemory = request.memory.storageMode === "filemem";
+    const memoryStoreName = isFileMemory
+      ? request.memory.memoryStoreName.trim()
+      : request.memory.memoryStoreName;
+    const wikiStoreName = isFileMemory
+      ? request.wiki.memoryStoreName.trim()
+      : request.wiki.memoryStoreName;
+    if (wikiStoreName !== memoryStoreName) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["wiki", "memoryStoreName"],
+        message: "Wiki and Memory stores must match",
+      });
+    }
+
+    const scopeFields = ["appId", "tenantId", "agentId"] as const;
+    scopeFields.forEach((field) => {
+      if (request.wiki?.scope[field] !== request.memory?.scope[field]) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ["wiki", "scope", field],
+          message: `Wiki and Memory scope.${field} must match`,
+        });
+      }
+    });
+  })
+  .transform((request) => {
+    if (request.memory?.storageMode !== "filemem") return request;
+
+    const memory = normalizeChatMemory(request.memory);
+    return {
+      ...request,
+      memory,
+      ...(request.wiki
+        ? {
+            wiki: {
+              ...request.wiki,
+              memoryStoreName: memory.memoryStoreName,
+              scope: memory.scope,
+            },
+          }
+        : {}),
+    };
+  });
 
 export type ChatRequestInput = z.infer<typeof chatRequestSchema>;

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

@@ -12,7 +12,9 @@ import type {
   DreamTaskSummary,
   MemoryRequestLog,
   MemoryScope,
-  MemorySearchHit,
+  ScopeDirectoryRequest,
+  ScopeDirectoryResponse,
+  SearchMemoryResponse,
   MemoryStore,
   MemoryTask,
   MemoryUnit,
@@ -131,11 +133,9 @@ export async function deleteMemoryUnit(
   );
 }
 
-export async function searchMemory(request: SearchMemoryRequest): Promise<{
-  results: MemorySearchHit[];
-  scope: MemoryScope;
-  memoryStoreName: string;
-}> {
+export async function searchMemory(
+  request: SearchMemoryRequest,
+): Promise<SearchMemoryResponse> {
   const { memoryStoreName, ...body } = request;
   return apiPost(
     `/api/v1/memory/stores/${encodeURIComponent(memoryStoreName)}/search`,
@@ -143,6 +143,16 @@ export async function searchMemory(request: SearchMemoryRequest): Promise<{
   );
 }
 
+export async function queryMemoryStoreScopes(
+  memoryStoreName: string,
+  request: ScopeDirectoryRequest,
+): Promise<ScopeDirectoryResponse> {
+  return apiPost(
+    `/api/v1/memory/stores/${encodeURIComponent(memoryStoreName)}/scopes`,
+    request,
+  );
+}
+
 export async function listMemoryMessages(
   memoryStoreName: string,
   scope: MemoryScope,

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

@@ -0,0 +1,145 @@
+import type {
+  AddWikiSourcesRequest,
+  DeleteWikiSourceRequest,
+  GetWikiPageRequest,
+  GetWikiSourceRequest,
+  IngestWikiRequest,
+  IngestWikiResponse,
+  ListWikiArtifactsRequest,
+  ListWikiArtifactsResponse,
+  ListWikiPagesRequest,
+  ListWikiPagesResponse,
+  ListWikiSourcesRequest,
+  ListWikiSourcesResponse,
+  SearchWikiPagesRequest,
+  UpdateWikiRequest,
+  UpdateWikiSourceRequest,
+  Wiki,
+  WikiPage,
+  WikiRawSource,
+  WikiScope,
+  WikiSourceBatchResult,
+} from "@/types/wiki";
+
+import { apiDelete, apiGet, apiPatch, apiPost, apiPut } from "./api-client";
+
+function wikisRoute(memoryStoreName: string): string {
+  return `/api/v1/memory/stores/${encodeURIComponent(memoryStoreName)}/wikis`;
+}
+
+export function buildWikiQuery(
+  scope: WikiScope,
+  extra: Record<string, number | string | undefined> = {},
+): string {
+  const params = new URLSearchParams();
+  params.set("appId", scope.appId);
+  params.set("tenantId", scope.tenantId);
+  params.set("agentId", scope.agentId);
+  for (const [key, value] of Object.entries(extra)) {
+    if (value !== undefined) params.set(key, String(value));
+  }
+  return params.toString();
+}
+
+export function getWiki(
+  memoryStoreName: string,
+  scope: WikiScope,
+): Promise<Wiki> {
+  return apiGet<Wiki>(
+    `${wikisRoute(memoryStoreName)}?${buildWikiQuery(scope)}`,
+  );
+}
+
+export function updateWiki(
+  memoryStoreName: string,
+  request: UpdateWikiRequest,
+): Promise<Wiki> {
+  return apiPatch<Wiki>(wikisRoute(memoryStoreName), request);
+}
+
+export function ingestWiki(
+  memoryStoreName: string,
+  request: IngestWikiRequest,
+): Promise<IngestWikiResponse> {
+  return apiPost(`${wikisRoute(memoryStoreName)}/ingest`, request);
+}
+
+export function listWikiSources(
+  memoryStoreName: string,
+  request: ListWikiSourcesRequest,
+): Promise<ListWikiSourcesResponse> {
+  const query = buildWikiQuery(request.scope, {
+    limit: request.limit,
+    nextToken: request.nextToken,
+  });
+  return apiGet(`${wikisRoute(memoryStoreName)}/sources?${query}`);
+}
+
+export function listWikiArtifacts(
+  memoryStoreName: string,
+  request: ListWikiArtifactsRequest,
+): Promise<ListWikiArtifactsResponse> {
+  const query = buildWikiQuery(request.scope, {
+    kind: request.kind,
+    limit: request.limit,
+    nextToken: request.nextToken,
+  });
+  return apiGet(`${wikisRoute(memoryStoreName)}/artifacts?${query}`);
+}
+
+export function addWikiSources(
+  memoryStoreName: string,
+  request: AddWikiSourcesRequest,
+): Promise<WikiSourceBatchResult> {
+  return apiPost(`${wikisRoute(memoryStoreName)}/sources`, request);
+}
+
+export function getWikiSource(
+  memoryStoreName: string,
+  request: GetWikiSourceRequest,
+): Promise<WikiRawSource> {
+  const query = buildWikiQuery(request.scope, { path: request.path });
+  return apiGet(`${wikisRoute(memoryStoreName)}/source?${query}`);
+}
+
+export function updateWikiSource(
+  memoryStoreName: string,
+  request: UpdateWikiSourceRequest,
+): Promise<WikiRawSource> {
+  return apiPut(`${wikisRoute(memoryStoreName)}/source`, request);
+}
+
+export function deleteWikiSource(
+  memoryStoreName: string,
+  request: DeleteWikiSourceRequest,
+): Promise<{ path: string; deleted: true }> {
+  return apiDelete(`${wikisRoute(memoryStoreName)}/source`, request);
+}
+
+export function listWikiPages(
+  memoryStoreName: string,
+  request: ListWikiPagesRequest,
+): Promise<ListWikiPagesResponse> {
+  const query = buildWikiQuery(request.scope, {
+    limit: request.limit,
+    nextToken: request.nextToken,
+  });
+  return apiGet(`${wikisRoute(memoryStoreName)}/pages?${query}`);
+}
+
+export function getWikiPage(
+  memoryStoreName: string,
+  request: GetWikiPageRequest,
+): Promise<WikiPage> {
+  const query = buildWikiQuery(request.scope, {
+    path: request.path,
+  });
+  return apiGet(`${wikisRoute(memoryStoreName)}/page?${query}`);
+}
+
+export function searchWikiPages(
+  memoryStoreName: string,
+  request: SearchWikiPagesRequest,
+): Promise<{ pages: WikiPage[] }> {
+  return apiPost(`${wikisRoute(memoryStoreName)}/search`, request);
+}