"use client"; import { createContext, useCallback, useContext, useMemo, useReducer, type ReactNode, } from "react"; import type { ChatRetrievalConfig, ChatSessionConfig, ChatSessionMount, } from "@/hooks/use-chat-history"; import type { ChatRequestBody } from "@/types/llm-chat"; import { assembleRetrievalConfiguration } from "@/components/retrieval/assemble-retrieval-configuration"; import { newId } from "@/lib/random-id"; import { FILEMEM_DEFAULT_RUN_ID, isKnownStorageMode, normalizeMemoryRunId, type StorageMode, } from "@/lib/memory-storage-mode"; export type MountItem = ChatSessionMount; /** * 绑定里存的 scope 是*写* scope:四个字段都齐全且非通配符。 * 服务端仅为结构化语义检索派生 app + tenant 级读 scope(保留 appId / tenantId, * agentId / runId 为 "*");文件记忆仍使用精确 scope。客户端永远 * 不发通配符。 */ export interface ChatMemoryWriteScope { appId: string; tenantId: string; agentId: string; runId: string; } export interface ChatMemoryBinding { id: string; memoryStoreName: string; storageMode?: StorageMode; scope: ChatMemoryWriteScope; topK?: number; autoSave: boolean; /** 缺省 "search"(语义检索);"local" 启用文件记忆(openclaw 同款)。 */ retrievalMode?: "search" | "local"; } export type ChatMemoryPatch = Partial< Omit > & { scope?: Partial }; export interface ChatConfigState { providerId: string; model: string; systemPrompt: string; temperature: number | undefined; aggregateTopK: number; perKbTopK: number; retrieval: ChatRetrievalConfig; mounts: MountItem[]; memory?: ChatMemoryBinding; wikiEnabled: boolean; wikiTopK: number; } /** Default aggregate topK applied when a session is first created. Mirrors * the server-side default in `chat/route.ts`. */ export const DEFAULT_AGGREGATE_TOP_K = 20; /** Default per-KB topK passed to each `retrieve` call. Matches the aggregate * cap so single-KB sessions get the full result set without truncation; * multi-KB sessions still benefit from the post-merge global rerank. */ export const DEFAULT_PER_KB_TOP_K = 20; export const DEFAULT_WIKI_TOP_K = 3; /** * Default unified retrieval parameters for a fresh session. Mirrors the * KB creation form so first-time users get a sensible hybrid setup without * having to manually tick both search types — dense + full-text combined * under weighted rerank (0.7 / 0.3) is the tablestore team's tuned baseline. */ export const DEFAULT_RETRIEVAL: ChatRetrievalConfig = { searchType: ["DENSE_VECTOR", "FULL_TEXT"], rerankType: "WEIGHT", weightDense: 0.7, weightFullText: 0.3, }; export const INITIAL_STATE: ChatConfigState = { providerId: "", model: "", systemPrompt: "", temperature: undefined, aggregateTopK: DEFAULT_AGGREGATE_TOP_K, perKbTopK: DEFAULT_PER_KB_TOP_K, retrieval: DEFAULT_RETRIEVAL, mounts: [], wikiEnabled: false, wikiTopK: DEFAULT_WIKI_TOP_K, }; type Action = | { type: "SET_PROVIDER"; providerId: string; model: string } | { type: "SET_MODEL"; model: string } | { type: "SET_SYSTEM_PROMPT"; value: string } | { type: "SET_TEMPERATURE"; value: number | undefined } | { type: "SET_AGGREGATE_TOP_K"; value: number } | { type: "SET_PER_KB_TOP_K"; value: number } | { type: "SET_RETRIEVAL"; value: ChatRetrievalConfig } | { type: "ADD_MOUNT"; mount: MountItem } | { type: "UPDATE_MOUNT"; id: string; patch: Partial } | { type: "RESET_MOUNT_RETRIEVAL"; id: string } | { type: "REMOVE_MOUNT"; id: string } | { type: "REORDER_MOUNTS"; ids: string[] } | { type: "SET_MEMORY"; binding: Omit | undefined } | { type: "UPDATE_MEMORY"; patch: ChatMemoryPatch } | { type: "SET_WIKI_ENABLED"; enabled: boolean } | { type: "SET_WIKI_TOP_K"; topK: number } | { type: "HYDRATE"; state: Partial } | { type: "RESET" }; function memoryBindingIdentity( memory: ChatMemoryBinding | undefined, ): string | undefined { if (!memory) return undefined; return JSON.stringify([ memory.memoryStoreName, memory.storageMode ?? null, memory.scope.appId, memory.scope.tenantId, memory.scope.agentId, memory.scope.runId, ]); } function normalizeMemoryBinding( binding: Omit, id: string, ): ChatMemoryBinding { return { id, ...binding, scope: { ...binding.scope, runId: normalizeMemoryRunId(binding.storageMode, binding.scope.runId), }, }; } function isExactMemoryBinding(memory: ChatMemoryBinding | undefined): boolean { if (!memory || !memory.memoryStoreName.trim()) return false; return Object.values(memory.scope).every((value) => { const normalized = value.trim(); return normalized.length > 0 && normalized !== "*"; }); } function hasExplicitKnownStorageMode( memory: ChatMemoryBinding | undefined, ): boolean { return isKnownStorageMode(memory?.storageMode); } export function isWikiEligibleMemoryBinding( memory: ChatMemoryBinding | undefined, ): boolean { return hasExplicitKnownStorageMode(memory) && isExactMemoryBinding(memory); } function sanitizeWikiTopK(raw: unknown): number { return typeof raw === "number" && Number.isInteger(raw) && raw >= 1 && raw <= 10 ? raw : DEFAULT_WIKI_TOP_K; } const HYDRATABLE_BASE_KEYS = [ "providerId", "model", "systemPrompt", "temperature", "aggregateTopK", "perKbTopK", "retrieval", "mounts", ] as const satisfies ReadonlyArray; function pickHydratableBaseState( state: Partial, ): Partial { return Object.fromEntries( HYDRATABLE_BASE_KEYS.filter((key) => Object.prototype.hasOwnProperty.call(state, key), ).map((key) => [key, state[key]]), ) as Partial; } export function reducer( state: ChatConfigState, action: Action, ): ChatConfigState { switch (action.type) { case "SET_PROVIDER": return { ...state, providerId: action.providerId, model: action.model }; case "SET_MODEL": return { ...state, model: action.model }; case "SET_SYSTEM_PROMPT": return { ...state, systemPrompt: action.value }; case "SET_TEMPERATURE": return { ...state, temperature: action.value }; case "SET_AGGREGATE_TOP_K": return { ...state, aggregateTopK: action.value }; case "SET_PER_KB_TOP_K": return { ...state, perKbTopK: action.value }; case "SET_RETRIEVAL": return { ...state, retrieval: action.value }; case "ADD_MOUNT": { // Skip if the same KB is already mounted — one mount per KB per session // keeps aggregation semantics simple. if ( state.mounts.some( (m) => m.knowledgeBaseName === action.mount.knowledgeBaseName, ) ) { return state; } return { ...state, mounts: [...state.mounts, action.mount] }; } case "UPDATE_MOUNT": return { ...state, mounts: state.mounts.map((m) => m.id === action.id ? { ...m, ...action.patch } : m, ), }; // 清除单 KB 的自定义检索参数:透过 partial spread 调用者不能以 undefined // 重置字段({ retrieval: undefined } 仍会使原始键存在),这里重建 mount // 折叠对象,确保字段从存在变为不存在,让后续 `??` fallback 生效。 case "RESET_MOUNT_RETRIEVAL": return { ...state, mounts: state.mounts.map((m) => { if (m.id !== action.id) return m; // 按需保留 id / knowledgeBaseName / subspace;丢弃 retrieval / topK。 const { retrieval: _retrieval, topK: _topK, ...rest } = m; void _retrieval; void _topK; return rest; }), }; case "REMOVE_MOUNT": return { ...state, mounts: state.mounts.filter((m) => m.id !== action.id), }; case "REORDER_MOUNTS": { const byId = new Map(state.mounts.map((m) => [m.id, m] as const)); const reordered = action.ids .map((id) => byId.get(id)) .filter((m): m is MountItem => !!m); return { ...state, mounts: reordered }; } case "HYDRATE": { const rawState = action.state; const { memory, wikiEnabled, wikiTopK } = rawState; const hydratedState = pickHydratableBaseState(rawState); const hasHydratedMemory = Object.prototype.hasOwnProperty.call( rawState, "memory", ); if (!hasHydratedMemory) { const requestedWikiEnabled = Object.prototype.hasOwnProperty.call( rawState, "wikiEnabled", ) ? wikiEnabled === true : state.wikiEnabled; return { ...state, ...hydratedState, wikiEnabled: requestedWikiEnabled && isWikiEligibleMemoryBinding(state.memory), ...(Object.prototype.hasOwnProperty.call(rawState, "wikiTopK") ? { wikiTopK: sanitizeWikiTopK(wikiTopK) } : {}), }; } if (!memory) { return { ...state, ...hydratedState, memory: undefined, wikiEnabled: false, wikiTopK: sanitizeWikiTopK(wikiTopK), }; } const normalizedMemory = normalizeMemoryBinding(memory, memory.id); return { ...state, ...hydratedState, memory: normalizedMemory, wikiEnabled: wikiEnabled === true && isWikiEligibleMemoryBinding(normalizedMemory), wikiTopK: sanitizeWikiTopK(wikiTopK), }; } // SET_MEMORY 同一绑定的 id 保持稳定;只有从无到有时才铸新 id,避免不必要的 React key 抖动。 case "SET_MEMORY": { if (!action.binding) { return { ...state, memory: undefined, wikiEnabled: false }; } const memory = normalizeMemoryBinding( action.binding, state.memory?.id ?? newId("memory"), ); return { ...state, memory, wikiEnabled: isWikiEligibleMemoryBinding(memory) && memoryBindingIdentity(state.memory) === memoryBindingIdentity(memory) ? state.wikiEnabled : false, }; } case "UPDATE_MEMORY": { if (!state.memory) return state; const { scope: patchScope, ...rest } = action.patch; const memory = { ...state.memory, ...rest, scope: { ...state.memory.scope, ...(patchScope ?? {}) }, }; const normalizedMemory = normalizeMemoryBinding(memory, memory.id); return { ...state, memory: normalizedMemory, wikiEnabled: isWikiEligibleMemoryBinding(normalizedMemory) && memoryBindingIdentity(state.memory) === memoryBindingIdentity(normalizedMemory) ? state.wikiEnabled : false, }; } case "SET_WIKI_ENABLED": return { ...state, wikiEnabled: action.enabled && isWikiEligibleMemoryBinding(state.memory), }; case "SET_WIKI_TOP_K": return sanitizeWikiTopK(action.topK) === action.topK ? { ...state, wikiTopK: action.topK } : state; case "RESET": return INITIAL_STATE; default: return state; } } export interface ChatConfigContextValue extends ChatConfigState { setProvider(providerId: string, model: string): void; setModel(model: string): void; setSystemPrompt(value: string): void; setTemperature(value: number | undefined): void; setAggregateTopK(value: number): void; setPerKbTopK(value: number): void; setRetrieval(value: ChatRetrievalConfig): void; addMount(mount: MountItem): void; updateMount(id: string, patch: Partial): void; /** Drop the per-KB retrieval/topK overrides for `id` so it inherits global defaults. */ resetMountRetrieval(id: string): void; removeMount(id: string): void; reorderMounts(ids: string[]): void; setMemory(binding: Omit | undefined): void; updateMemory(patch: ChatMemoryPatch): void; setWikiEnabled(enabled: boolean): void; setWikiTopK(topK: number): void; hydrate(state: Partial): void; reset(): void; /** Serialize the current config for persistence into a chat session. */ toSessionConfig(): ChatSessionConfig; } const ChatConfigContext = createContext(null); export function ChatConfigProvider({ children }: { children: ReactNode }) { const [state, dispatch] = useReducer(reducer, INITIAL_STATE); const value = useMemo( () => ({ ...state, setProvider: (providerId, model) => dispatch({ type: "SET_PROVIDER", providerId, model }), setModel: (model) => dispatch({ type: "SET_MODEL", model }), setSystemPrompt: (v) => dispatch({ type: "SET_SYSTEM_PROMPT", value: v }), setTemperature: (v) => dispatch({ type: "SET_TEMPERATURE", value: v }), setAggregateTopK: (v) => dispatch({ type: "SET_AGGREGATE_TOP_K", value: v }), setPerKbTopK: (v) => dispatch({ type: "SET_PER_KB_TOP_K", value: v }), setRetrieval: (v) => dispatch({ type: "SET_RETRIEVAL", value: v }), addMount: (m) => dispatch({ type: "ADD_MOUNT", mount: m }), updateMount: (id, patch) => dispatch({ type: "UPDATE_MOUNT", id, patch }), resetMountRetrieval: (id) => dispatch({ type: "RESET_MOUNT_RETRIEVAL", id }), removeMount: (id) => dispatch({ type: "REMOVE_MOUNT", id }), reorderMounts: (ids) => dispatch({ type: "REORDER_MOUNTS", ids }), setMemory: (b) => dispatch({ type: "SET_MEMORY", binding: b }), updateMemory: (p) => dispatch({ type: "UPDATE_MEMORY", patch: p }), setWikiEnabled: (enabled) => dispatch({ type: "SET_WIKI_ENABLED", enabled }), setWikiTopK: (topK) => dispatch({ type: "SET_WIKI_TOP_K", topK }), hydrate: (s) => dispatch({ type: "HYDRATE", state: s }), reset: () => dispatch({ type: "RESET" }), toSessionConfig: () => ({ providerId: state.providerId || undefined, model: state.model || undefined, systemPrompt: state.systemPrompt || undefined, temperature: state.temperature, aggregateTopK: state.aggregateTopK, perKbTopK: state.perKbTopK, retrieval: state.retrieval, mounts: state.mounts, memory: state.memory, ...(state.wikiEnabled && isWikiEligibleMemoryBinding(state.memory) ? { wiki: { enabled: true as const, topK: state.wikiTopK } } : {}), }), }), [state], ); return ( {children} ); } export function useChatConfig(): ChatConfigContextValue { const ctx = useContext(ChatConfigContext); if (!ctx) { throw new Error("useChatConfig must be used within a ChatConfigProvider"); } return ctx; } /** * Build the RAG slice of a chat request body from the current mounts, or * return undefined when no KB is mounted. Kept as a plain helper so it can * run outside React rendering (e.g. in onClick handlers). * * 每个 mount 优先使用自己的 `retrieval` / `topK` override;未设置时 fallback * 到会话级的 `state.retrieval` / `state.perKbTopK`。上层在 chat route 合并后 * 仍由 `state.aggregateTopK` 统一截断,跨 KB 的打分可比性责任交给服务端。 */ export function buildRagFromMounts(state: ChatConfigState) { if (!state.mounts.length) return undefined; return { knowledgeBases: state.mounts.map((m) => { const effectiveRetrieval = m.retrieval ?? state.retrieval; const effectiveTopK = m.topK ?? state.perKbTopK; const retrievalConfiguration = assembleRetrievalConfiguration( effectiveRetrieval, effectiveTopK, ); return { knowledgeBaseName: m.knowledgeBaseName, ...(m.subspace?.length ? { subspace: m.subspace } : {}), ...(retrievalConfiguration ? { retrievalConfiguration: retrievalConfiguration as Record< string, unknown >, } : {}), topK: effectiveTopK, }; }), topK: state.aggregateTopK, }; } /** * 把当前绑定序列化成 `/api/v1/llm/chat` 请求体里的 `memory` 段。 * 任一 scope 字段为空 ⇒ 视作未绑定,返回 undefined。 */ export function buildMemoryFromBinding(state: ChatConfigState) { const m = state.memory; if (!m) return undefined; const { appId, tenantId, agentId } = m.scope; const runId = m.storageMode === "filemem" ? FILEMEM_DEFAULT_RUN_ID : m.scope.runId; if (!appId || !tenantId || !agentId || !runId) return undefined; return { memoryStoreName: m.memoryStoreName, scope: { appId, tenantId, agentId, runId }, ...(m.storageMode ? { storageMode: m.storageMode } : {}), ...(typeof m.topK === "number" ? { topK: m.topK } : {}), autoSave: m.autoSave, ...(m.retrievalMode ? { retrievalMode: m.retrievalMode } : {}), }; } export function buildWikiFromBinding( state: ChatConfigState, ): ChatRequestBody["wiki"] | undefined { if (!state.wikiEnabled || !isWikiEligibleMemoryBinding(state.memory)) { return undefined; } const memory = state.memory as ChatMemoryBinding; return { memoryStoreName: memory.memoryStoreName, scope: memory.scope, topK: state.wikiTopK, }; } /** Hook shortcut so downstream components don't have to re-derive the rag. */ export function useChatRag() { const cfg = useChatConfig(); return useCallback(() => buildRagFromMounts(cfg), [cfg]); }