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
/**
* Tool Capability Requirements
*
* Single source of truth for the mapping from agent tool names to the
* knowledge-base capabilities each tool depends on. Used to:
* - Gray out tools whose dependencies aren't satisfied by the current scope
* (see `AgentEditorModal.vue` → `availableTools`).
* - Derive `kb_filter`-style predicates for agent type presets so the same
* declarative map drives both the tool allowlist and the KB allowlist
* (see `deriveKbFilterFromTools`).
*
* Capability names mirror the backend's KB capability set:
* - vector: vector chunk index (embedding-based retrieval)
* - keyword: keyword/BM25 chunk index
* - wiki: Wiki page indexing
* - graph: knowledge graph index
* - faq: FAQ-type KB (question/answer pairs as chunks)
*
* Requirement semantics:
* - `anyOf`: KB scope must expose at least ONE listed capability.
* - `allOf`: KB scope must expose ALL listed capabilities.
* - empty : tool has no KB requirement (always available).
*
* IMPORTANT: keep this list aligned with backend tool definitions
* (`internal/agent/tools/`; this map mirrors
* `internal/agent/tools/capabilities.go`). A tool missing from this map
* defaults to "always available" so new tools don't silently start disabled.
*/
export type KBCapability = 'vector' | 'keyword' | 'wiki' | 'graph' | 'faq';
export interface ToolRequirement {
anyOf?: KBCapability[];
allOf?: KBCapability[];
/**
* Auxiliary tools work on the listed KBs but do not by themselves make a KB
* worth selecting (a document reader can open a wiki-only KB's sources, yet
* must not pull wiki-only KBs into a RAG agent's scope). They only shape
* the derived KB filter when no primary tool has a requirement. Mirrors
* `ToolRequirement.Auxiliary` in `internal/agent/tools/capabilities.go`.
*/
auxiliary?: boolean;
/**
* Whether this tool can use user-provided file references (via @ 提及) as
* an additional retrieval scope. Tools with `consumesFiles: false` ignore
* `knowledge_ids`; we use this flag in the chat `@` dropdown to decide
* whether to even offer the "文件" tab to the user.
*/
consumesFiles?: boolean;
}
export const TOOL_CAPABILITY_REQUIREMENTS: Record<string, ToolRequirement> = {
// ---- base / reasoning (no KB dependency) ----
thinking: {},
todo_write: {},
ask_user: {},
// ---- RAG / chunk retrieval (need at least one chunk-indexed KB) ----
// We use vector|keyword as the canonical "has RAG chunks" signal. FAQ KBs
// also expose chunks, but the current UX message bucket is "RAG KB"; once
// we add a dedicated `requiresFaqKb` i18n key we can include `faq` here.
search_knowledge: { anyOf: ['vector', 'keyword'], consumesFiles: true },
// Document readers work on stored chunks, which wiki-only KBs have too.
read_document: { anyOf: ['vector', 'keyword', 'wiki'], consumesFiles: true, auxiliary: true },
list_documents: { anyOf: ['vector', 'keyword', 'wiki'], consumesFiles: true, auxiliary: true },
database_query: { anyOf: ['vector', 'keyword'], consumesFiles: true },
// Retired names kept so stale agent configs / stored history still resolve.
// The editor normalizes them to the new names on load (see
// `@/utils/legacy-tool-names`).
knowledge_search: { anyOf: ['vector', 'keyword'], consumesFiles: true },
grep_chunks: { anyOf: ['vector', 'keyword'], consumesFiles: true },
list_knowledge_chunks: { anyOf: ['vector', 'keyword'], consumesFiles: true },
get_document_info: { anyOf: ['vector', 'keyword'], consumesFiles: true },
wiki_read_source_doc: { anyOf: ['vector', 'keyword', 'wiki'], consumesFiles: true, auxiliary: true },
// ---- Knowledge graph (needs a graph-indexed KB) ----
query_knowledge_graph: { allOf: ['graph'], consumesFiles: true },
// ---- Wiki (operates on wiki pages referenced by the wiki machinery;
// arbitrary user-picked file IDs aren't meaningful here) ----
wiki_search: { allOf: ['wiki'] },
wiki_read_page: { allOf: ['wiki'] },
wiki_flag_issue: { allOf: ['wiki'] },
wiki_write_page: { allOf: ['wiki'] },
wiki_replace_text: { allOf: ['wiki'] },
wiki_rename_page: { allOf: ['wiki'] },
wiki_delete_page: { allOf: ['wiki'] },
wiki_read_issue: { allOf: ['wiki'] },
wiki_update_issue: { allOf: ['wiki'] },
// ---- Data analysis (reads table summary/column chunks produced by RAG ingest) ----
data_analysis: { anyOf: ['vector', 'keyword'], consumesFiles: true },
data_schema: { anyOf: ['vector', 'keyword'], consumesFiles: true },
};
/**
* Aggregate KB-capability set available somewhere in the agent's KB scope.
* All fields default to `false` for unknown capabilities.
*/
export interface ScopeCapabilities {
vector: boolean;
keyword: boolean;
wiki: boolean;
graph: boolean;
faq: boolean;
}
/**
* Machine-readable reason a tool is unsatisfiable. Map to a user-facing
* string via i18n on the caller side (see `AgentEditorModal.vue`).
*/
export type RequirementMissKind = 'none' | 'needsKb' | 'needsRag' | 'needsWiki' | 'needsGraph' | 'needsFaq';
/**
* Evaluate whether a tool's requirements are satisfied by the scope.
*
* @param toolName the tool identifier (see `TOOL_CAPABILITY_REQUIREMENTS`)
* @param scope aggregate capabilities exposed by KBs currently in scope
* @param hasAnyKb whether the agent has at least one KB in scope
* (i.e. `kb_selection_mode !== 'none'`)
*/
export function evaluateToolRequirement(
toolName: string,
scope: ScopeCapabilities,
hasAnyKb: boolean,
): { ok: boolean; missKind: RequirementMissKind } {
return evaluateRequirement(TOOL_CAPABILITY_REQUIREMENTS[toolName], scope, hasAnyKb);
}
/**
* Evaluate a requirement given directly, such as one served by the backend
* tool catalog (`GET /api/v1/agents/tools`). An absent or empty requirement
* is always satisfied.
*/
export function evaluateRequirement(
req: Pick<ToolRequirement, 'anyOf' | 'allOf'> | undefined,
scope: ScopeCapabilities,
hasAnyKb: boolean,
): { ok: boolean; missKind: RequirementMissKind } {
// No requirements: always available.
if (!req || (!req.anyOf?.length && !req.allOf?.length)) {
return { ok: true, missKind: 'none' };
}
// Any capability requirement implies needing at least one KB in scope.
if (!hasAnyKb) return { ok: false, missKind: 'needsKb' };
const has = (c: KBCapability): boolean => !!scope[c];
if (req.allOf && req.allOf.length > 0) {
for (const c of req.allOf) {
if (!has(c)) return { ok: false, missKind: primaryMissKind(c) };
}
}
if (req.anyOf && req.anyOf.length > 0) {
if (!req.anyOf.some(has)) {
return { ok: false, missKind: primaryMissKind(req.anyOf[0]) };
}
}
return { ok: true, missKind: 'none' };
}
function primaryMissKind(c: KBCapability): RequirementMissKind {
switch (c) {
case 'wiki': return 'needsWiki';
case 'graph': return 'needsGraph';
case 'faq': return 'needsFaq';
case 'vector':
case 'keyword': return 'needsRag';
}
}
/**
* Derive a `kb_filter`-style predicate for a list of tools: a KB satisfies
* the derived filter iff at least ONE of the listed tools would be usable
* on a scope consisting of just that KB.
*
* Used by Step 3 so presets don't have to hand-maintain `kb_filter` next
* to their `allowed_tools` — the two are always derived from the same map.
*
* Returns `null` when none of the input tools have any KB requirement
* (i.e. any KB is acceptable).
*/
export function deriveKbFilterFromTools(
tools: string[],
): { any_of: KBCapability[] } | null {
const primary = new Set<KBCapability>();
const auxiliary = new Set<KBCapability>();
for (const t of tools) {
const req = TOOL_CAPABILITY_REQUIREMENTS[t];
if (!req) continue;
const target = req.auxiliary ? auxiliary : primary;
req.anyOf?.forEach(c => target.add(c));
req.allOf?.forEach(c => target.add(c));
}
const caps = primary.size > 0 ? primary : auxiliary;
if (caps.size === 0) return null;
return { any_of: Array.from(caps) };
}
/**
* Implicit KB capability requirement for the "quick-answer" (RAG) agent
* mode. Quick-answer drives retrieval purely through vector/keyword chunk
* search and ships with NO `allowed_tools`, so the tool-derived filter
* alone would let wiki-only KBs through even though they can't contribute
* anything to a RAG answer. Treat this as a property of the agent MODE.
*/
const QUICK_ANSWER_KB_FILTER: { any_of: KBCapability[] } = {
any_of: ['vector', 'keyword'],
};
/**
* Agent-mode aware version of `deriveKbFilterFromTools`: unions the
* tool-derived `any_of` with the implicit requirement of `agentMode`
* (currently: quick-answer → vector|keyword).
*
* Returns `null` when neither the agent mode nor the tools impose any
* capability constraint (i.e. any KB is acceptable).
*/
export function deriveKbFilterForAgent(
agentMode: string | undefined | null,
allowedTools: string[] | undefined | null,
): { any_of: KBCapability[] } | null {
const caps = new Set<KBCapability>();
if (agentMode === 'quick-answer') {
QUICK_ANSWER_KB_FILTER.any_of.forEach(c => caps.add(c));
}
const fromTools = deriveKbFilterFromTools(allowedTools || []);
fromTools?.any_of.forEach(c => caps.add(c));
if (caps.size === 0) return null;
return { any_of: Array.from(caps) };
}
/**
* Agent-mode aware version of `kbSatisfiesToolRequirements`: ALSO honours
* the implicit capability requirement of `agentMode` (quick-answer needs
* vector or keyword indexing). Use this anywhere the user is choosing a
* KB for an agent — agent editor "specified KB" dropdown, chat `@`
* mention list, etc.
*/
export function kbSatisfiesAgentRequirements(
kbCaps: Partial<ScopeCapabilities> | undefined | null,
agentMode: string | undefined | null,
allowedTools: string[] | undefined | null,
): boolean {
const filter = deriveKbFilterForAgent(agentMode, allowedTools);
if (!filter) return true;
if (!kbCaps) return false;
return filter.any_of.some(c => !!kbCaps[c]);
}
/**
* Decide whether a single KB is compatible with an agent's tool set.
*
* "Compatible" here means: at least ONE tool in `allowedTools` requires a
* capability that this KB exposes — i.e. the agent has SOMETHING useful to
* do against this KB. Tools with no KB requirement don't contribute.
*
* If `allowedTools` contains no KB-dependent tool, every KB is considered
* compatible (the agent won't retrieve anything either way, so filtering
* is not meaningful).
*/
export function kbSatisfiesToolRequirements(
kbCaps: Partial<ScopeCapabilities> | undefined | null,
allowedTools: string[] | undefined | null,
): boolean {
const filter = deriveKbFilterFromTools(allowedTools || []);
if (!filter) return true;
if (!kbCaps) return false;
return filter.any_of.some(c => !!kbCaps[c]);
}
/**
* True iff any of the agent's allowed tools can consume user-provided file
* references (`knowledge_ids`). Used by the chat `@` menu to decide whether
* showing the "文件" list makes sense at all — e.g. a pure Wiki agent has no
* tool that would read an arbitrary file the user picks, so we don't offer
* it. `undefined`/`null`/empty → true (permissive fallback: if we don't
* know, show files).
*/
export function toolsConsumeFiles(
allowedTools: string[] | undefined | null,
): boolean {
if (!allowedTools || allowedTools.length === 0) return true;
for (const t of allowedTools) {
const req = TOOL_CAPABILITY_REQUIREMENTS[t];
// Unknown tools (e.g. MCP tools) are treated as potentially file-consuming.
if (!req) return true;
if (req.consumesFiles) return true;
}
return false;
}