Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
import type { KnowledgeFolderNode, KnowledgeFolderTree } from '@/api/knowledge-base/index'
/**
* Pure helpers behind the knowledge base folder sidebar.
*
* A folder selection is just a path, where the empty string is the knowledge
* base root. The root is a real node of the tree — every top-level folder is
* its child — so there is no separate "all documents" pseudo-row: what the root
* row lists is decided by the same recursive switch as any other folder.
*/
export const ROOT_FOLDER_PATH = ''
/** Keep in sync with types.MaxKnowledgeFolderDepth on the server. */
export const MAX_FOLDER_DEPTH = 16
/** Keep in sync with types.MaxKnowledgeFolderSegmentLength on the server. */
export const MAX_FOLDER_SEGMENT_LENGTH = 128
/** Keep in sync with types.MaxKnowledgeFolderPathLength on the server. */
export const MAX_FOLDER_PATH_LENGTH = 1024
/** Minimal shape of the browser File objects the upload flow deals with. */
export type UploadFileLike = {
name: string
webkitRelativePath?: string
}
/**
* A folder listed as a row or card in the document list. It is the subset of a
* tree node the list needs: the path to navigate to and the two counts.
*/
export type FolderEntry = Pick<
KnowledgeFolderNode,
'path' | 'name' | 'document_count' | 'total_count'
>
/**
* One rendered row of the flattened tree. The root row carries the knowledge
* base totals; the component supplies its label.
*/
export type FolderRow = {
kind: 'root' | 'folder'
path: string
name: string
depth: number
/** Documents stored directly in this folder. */
documentCount: number
/** Documents in this folder plus every descendant folder. */
totalCount: number
hasChildren: boolean
}
/**
* A browser only sets webkitRelativePath when the file came from a directory
* picker or a dropped directory, which is exactly what distinguishes a folder
* upload from picking individual files.
*/
export function isFolderUpload(file: UploadFileLike): boolean {
return !!file.webkitRelativePath
}
/**
* Build the path-qualified `fileName` form field that the backend splits into
* folder_path + file_name. Two sources are combined: the destination folder
* chosen for the batch and the browser's webkitRelativePath, whose picked
* directory becomes a folder under that destination.
*
* Returns undefined for a plain single-file upload into the root so that request
* stays byte-identical to the pre-folder behaviour.
*/
export function buildUploadFileName(
file: UploadFileLike,
targetFolder: string,
): string | undefined {
const segments: string[] = []
if (targetFolder) segments.push(targetFolder)
if (file.webkitRelativePath) {
segments.push(...file.webkitRelativePath.split('/').filter(Boolean).slice(0, -1))
}
if (segments.length === 0) return undefined
return `${segments.join('/')}/${file.name}`
}
/**
* Breadcrumb entries for a folder path, from the top level down to the leaf.
* The root has no crumbs of its own — callers render it as the leading item.
*/
export function folderBreadcrumbs(path: string): Array<{ name: string; path: string }> {
if (!path) return []
const segments = path.split('/')
return segments.map((name, index) => ({
name,
path: segments.slice(0, index + 1).join('/'),
}))
}
/**
* The root, the path itself and every folder in between, used to keep the
* selected folder reachable by expanding the rows above it.
*/
export function folderAncestorPaths(path: string): string[] {
const paths = [ROOT_FOLDER_PATH]
if (!path) return paths
const segments = path.split('/')
segments.forEach((_, index) => paths.push(segments.slice(0, index + 1).join('/')))
return paths
}
/** Depth-first search for a folder path in the tree. The root always exists. */
export function folderPathExists(folders: KnowledgeFolderNode[], path: string): boolean {
if (path === ROOT_FOLDER_PATH) return true
return folders.some((node) => node.path === path || folderPathExists(node.children || [], path))
}
function flattenFolders(
folders: KnowledgeFolderNode[],
expanded: Set<string>,
depth: number,
): FolderRow[] {
const rows: FolderRow[] = []
folders.forEach((node) => {
const hasChildren = !!node.children?.length
rows.push({
kind: 'folder',
path: node.path,
name: node.name,
depth,
documentCount: node.document_count,
totalCount: node.total_count,
hasChildren,
})
if (hasChildren && expanded.has(node.path)) {
rows.push(...flattenFolders(node.children!, expanded, depth + 1))
}
})
return rows
}
/**
* Flatten the tree into the visible rows: the root first, then the folders
* nested beneath it, honouring the expanded set at every level.
*/
export function buildFolderRows(
tree: KnowledgeFolderTree | null,
expanded: Set<string>,
): FolderRow[] {
const folders = tree?.folders ?? []
const root: FolderRow = {
kind: 'root',
path: ROOT_FOLDER_PATH,
name: '',
depth: 0,
documentCount: tree?.root_document_count ?? 0,
totalCount: tree?.total_document_count ?? 0,
hasChildren: folders.length > 0,
}
if (!root.hasChildren || !expanded.has(ROOT_FOLDER_PATH)) return [root]
return [root, ...flattenFolders(folders, expanded, 1)]
}
/** Depth-first lookup of one folder node anywhere in the tree. */
function findFolderNode(
folders: KnowledgeFolderNode[],
path: string,
): KnowledgeFolderNode | undefined {
for (const node of folders) {
if (node.path === path) return node
const found = findFolderNode(node.children || [], path)
if (found) return found
}
return undefined
}
/**
* Direct sub-folders of a folder: the rows the sidebar tree renders underneath
* it. The root's children are the top-level folders.
*/
export function childFolders(
tree: KnowledgeFolderTree | null,
path: string,
): KnowledgeFolderNode[] {
const folders = tree?.folders ?? []
if (path === ROOT_FOLDER_PATH) return folders
return findFolderNode(folders, path)?.children ?? []
}
/**
* How many documents a folder holds: the ones stored directly in it, and the
* ones in its whole subtree. Returns null when the tree is unavailable or the
* path is not in it, so callers can fall back to the loaded document list.
*
* The two numbers differ as soon as folders nest: a parent that only groups
* sub-folders has 0 direct documents but a non-zero total, and showing the
* direct count there reads as "empty".
*/
export function folderDocumentCounts(
tree: KnowledgeFolderTree | null,
path: string,
): { direct: number; total: number } | null {
if (!tree) return null
if (path === ROOT_FOLDER_PATH) {
return { direct: tree.root_document_count ?? 0, total: tree.total_document_count ?? 0 }
}
const node = findFolderNode(tree.folders ?? [], path)
if (!node) return null
return { direct: node.document_count ?? 0, total: node.total_count ?? 0 }
}
/**
* Whether the document list is filtering rather than browsing.
*
* This is the single input that decides how a folder selection is read, and it
* comes from what the user is already doing instead of from a mode switch they
* have to understand:
*
* - Browsing (no filter active) lists the selected folder's own contents — its
* sub-folders as entries plus the documents directly inside it, the way a file
* manager does. A document uploaded on its own therefore sits at the top level
* next to the folders, which is exactly where it belongs.
* - Filtering searches the selected folder and everything below it, returning a
* flat result set, because a search that stopped at one level would hide
* matches for no good reason.
*/
export function isFilteringDocuments(filters: {
keyword?: string
tagIds?: string[]
fileType?: string
parseStatus?: string
source?: string
timeRange?: string[]
}): boolean {
return !!(
filters.keyword?.trim() ||
filters.tagIds?.length ||
filters.fileType ||
filters.parseStatus ||
filters.source ||
filters.timeRange?.filter(Boolean).length
)
}
/**
* Canonicalize a user-typed folder path the same way the server does, so the
* move dialog can preview and compare the destination it is about to send.
*/
export function normalizeFolderPath(path: string): string {
const segments: string[] = []
for (const raw of path.replace(/\\/g, '/').split('/')) {
let segment = raw.trim().replace(/[. ]+$/, '')
if (!segment || segment === '.' || segment === '..') continue
if (segment.length > MAX_FOLDER_SEGMENT_LENGTH) {
segment = segment.slice(0, MAX_FOLDER_SEGMENT_LENGTH).trim()
}
if (!segment) continue
segments.push(segment)
if (segments.length >= MAX_FOLDER_DEPTH) break
}
let normalized = segments.join('/')
while (normalized.length > MAX_FOLDER_PATH_LENGTH && segments.length > 0) {
segments.pop()
normalized = segments.join('/')
}
return normalized
}
/** Destination path for a new sub-folder of `parent`. */
export function joinFolderPath(parent: string, name: string): string {
return normalizeFolderPath(parent ? `${parent}/${name}` : name)
}
/** Flat picker row for a canonical folder path (used for optimistic create rows). */
export function folderOptionFromPath(path: string): { path: string; name: string; depth: number } {
const segments = path.split('/').filter(Boolean)
return {
path,
name: segments[segments.length - 1] || path,
depth: Math.max(segments.length - 1, 0),
}
}
/** Sort folder picker rows in tree order (parent before child, siblings lexicographic). */
export function sortFolderOptions<T extends { path: string }>(options: T[]): T[] {
return [...options].sort((a, b) => {
const aParts = a.path.split('/').filter(Boolean)
const bParts = b.path.split('/').filter(Boolean)
const max = Math.max(aParts.length, bParts.length)
for (let i = 0; i < max; i += 1) {
const aSeg = aParts[i]
const bSeg = bParts[i]
if (aSeg === undefined) return -1
if (bSeg === undefined) return 1
const cmp = aSeg.localeCompare(bSeg)
if (cmp !== 0) return cmp
}
return 0
})
}
/**
* Whether a folder can be renamed/moved to `to`: a folder cannot land inside its
* own subtree, which would make that subtree unreachable.
*/
export function canMoveFolderTo(from: string, to: string): boolean {
const source = normalizeFolderPath(from)
const target = normalizeFolderPath(to)
if (!source || !target) return false
if (target === source) return false
return !target.startsWith(`${source}/`)
}