Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
fix(docs): localize OpenViking search UI (#2711)
Hao Zheb1712aab2812
diff --git a/.github/workflows/_docs.yml b/.github/workflows/_docs.ymlindex 63a098352..5350d24c4 100644--- a/.github/workflows/_docs.yml+++ b/.github/workflows/_docs.yml@@ -24,6 +24,10 @@ jobs:run: npm ciworking-directory: docs+ - name: Test docs search+ run: npm run test:search+ working-directory: docs+- name: Build docsrun: npm run docs:buildworking-directory: docsdiff --git a/docs/.vitepress/theme/OpenVikingSearch.vue b/docs/.vitepress/theme/OpenVikingSearch.vueindex 131d033a5..5f2262c67 100644--- a/docs/.vitepress/theme/OpenVikingSearch.vue+++ b/docs/.vitepress/theme/OpenVikingSearch.vue@@ -1,36 +1,22 @@<script setup lang="ts">import { computed, nextTick, onMounted, onUnmounted, ref, watch } from 'vue'-import { withBase } from 'vitepress'--type SearchMode = 'semantic' | 'keyword' | 'file'-type SearchLocale = 'en' | 'zh'--type DocsIndexRecord = {- locale: SearchLocale- path: string- text: string- title: string- url: string-}--type DocsSearchResult = {- line?: number | null- mode?: SearchMode- relativePath?: string- score?: number | null- snippet?: string- title?: string- uri?: string- url?: string-}+import { useData, withBase } from 'vitepress'++import { searchCopyForLocale } from './openviking-search-i18n'+import { localizeSearchResultTitles } from './openviking-search-results'+import type { RemoteSearchFailureReason } from './openviking-search-i18n'+import type {+ DocsIndexRecord,+ DocsSearchResult,+ SearchLocale,+ SearchMode+} from './openviking-search-results'type ResolvedDocsSearchResult = DocsSearchResult & {cleanedSnippet: stringresolvedUrl: string}-type RemoteSearchFailureReason = 'rate_limited' | 'timeout' | 'unavailable'-type RemoteSearchResponse =| { ok: true; results: DocsSearchResult[] }| { ok: false; reason: RemoteSearchFailureReason }@@ -38,29 +24,16 @@ type RemoteSearchResponse =const PRODUCTION_SEARCH_URL = 'https://openviking.ai/studio/gateway/docs/search'const SEARCH_LIMIT = 8const REMOTE_SEARCH_DEBOUNCE_MS = 1000-const REMOTE_SEARCH_TIMEOUT_MS = 10000--const modes: { command: string; label: string; placeholder: string; value: SearchMode }[] = [- {- command: '/find',- label: 'Semantic',- placeholder: 'Ask a question about the docs',- value: 'semantic'- },- {- command: '/grep',- label: 'Keyword',- placeholder: 'Search exact words in the docs',- value: 'keyword'- },- {- command: '/glob',- label: 'File',- placeholder: 'Find docs by path or filename',- value: 'file'- }+const REMOTE_SEARCH_TIMEOUT_MS = 15000++const modeDefinitions: { command: string; value: SearchMode }[] = [+ { command: '/find', value: 'semantic' },+ { command: '/grep', value: 'keyword' },+ { command: '/glob', value: 'file' }]+const { lang } = useData()+const inputRef = ref<HTMLInputElement | null>(null)const triggerRef = ref<HTMLButtonElement | null>(null)const dialogRef = ref<HTMLElement | null>(null)@@ -79,7 +52,14 @@ let localIndexPromise: Promise<DocsIndexRecord[]> | null = nulllet activeSearchController: AbortController | null = nullconst trimmedQuery = computed(() => query.value.trim())-const activeMode = computed(() => modes.find((item) => item.value === mode.value) ?? modes[0])+const searchCopy = computed(() => searchCopyForLocale(docsLocale()))+const modes = computed(() =>+ modeDefinitions.map((item) => ({+ ...item,+ ...searchCopy.value.modes[item.value]+ }))+)+const activeMode = computed(() => modes.value.find((item) => item.value === mode.value) ?? modes.value[0])const resolvedResults = computed<ResolvedDocsSearchResult[]>(() =>results.value.flatMap((result) => {const resolvedUrl = resultUrl(result)@@ -88,6 +68,12 @@ const resolvedResults = computed<ResolvedDocsSearchResult[]>(() =>)function docsLocale(): SearchLocale {+ const currentLang = String(lang.value ?? '').toLowerCase()+ if (currentLang.startsWith('zh')) return 'zh'+ if (currentLang.startsWith('en')) return 'en'++ if (typeof window === 'undefined') return 'en'+const basePath = normalizeBasePath(import.meta.env.BASE_URL)const pathname = window.location.pathnameconst localizedPath = pathname.startsWith(basePath)@@ -232,7 +218,7 @@ async function runSearch() {if (currentSequence !== searchSequence) returnif (remoteResponse?.ok) {- results.value = remoteResponse.results+ results.value = await localizeRemoteResultTitles(remoteResponse.results, docsLocale())return}@@ -253,6 +239,13 @@ async function runSearch() {}}+async function localizeRemoteResultTitles(+ searchResults: DocsSearchResult[],+ locale: SearchLocale+) {+ return localizeSearchResultTitles(searchResults, locale, loadLocalIndex)+}+async function fetchRemoteResults(endpoint: string,searchQuery: string,@@ -321,16 +314,7 @@ function clearPendingSearch() {}function fallbackNotice(reason: RemoteSearchFailureReason, localResultCount: number) {- const prefix =- reason === 'rate_limited'- ? 'OpenViking search is rate limited.'- : reason === 'timeout'- ? 'OpenViking search timed out.'- : 'OpenViking search is unavailable.'-- return localResultCount > 0- ? `${prefix} Showing local docs results.`- : `${prefix} No local results found.`+ return searchCopy.value.notice(reason, localResultCount)}async function loadLocalIndex() {@@ -484,13 +468,13 @@ onUnmounted(() => {<div class="ov-docs-search"><buttonref="triggerRef"- aria-label="Search docs"+ :aria-label="searchCopy.trigger"class="ov-docs-search-trigger"type="button"@click="openSearch">- <span class="ov-docs-search-trigger-label">Search docs</span>- <span aria-hidden="true" class="ov-docs-search-trigger-compact">Search</span>+ <span class="ov-docs-search-trigger-label">{{ searchCopy.trigger }}</span>+ <span aria-hidden="true" class="ov-docs-search-trigger-compact">{{ searchCopy.compactTrigger }}</span><kbd>Ctrl K</kbd></button>@@ -498,7 +482,7 @@ onUnmounted(() => {<div class="ov-docs-search-backdrop" @click.self="closeSearch"><sectionref="dialogRef"- aria-label="OpenViking docs search"+ :aria-label="searchCopy.dialogLabel"aria-modal="true"class="ov-docs-search-dialog"role="dialog"@@ -510,7 +494,7 @@ onUnmounted(() => {aria-controls="ov-docs-search-mode-menu":aria-expanded="isModeMenuOpen"aria-haspopup="listbox"- aria-label="Search mode"+ :aria-label="searchCopy.modeLabel"class="ov-docs-search-mode-button"type="button"@click="toggleModeMenu"@@ -522,7 +506,7 @@ onUnmounted(() => {<divv-if="isModeMenuOpen"id="ov-docs-search-mode-menu"- aria-label="Search mode options"+ :aria-label="searchCopy.modeOptionsLabel"class="ov-docs-search-mode-menu"role="listbox">@@ -545,7 +529,7 @@ onUnmounted(() => {<inputref="inputRef"v-model="query"- aria-label="Search OpenViking docs"+ :aria-label="searchCopy.inputLabel"class="ov-docs-search-input":placeholder="activeMode.placeholder"type="search"@@ -556,12 +540,12 @@ onUnmounted(() => {<p v-if="notice" class="ov-docs-search-notice">{{ notice }}</p><div class="ov-docs-search-results">- <p v-if="isLoading" class="ov-docs-search-empty">Searching...</p>+ <p v-if="isLoading" class="ov-docs-search-empty">{{ searchCopy.empty.loading }}</p><p v-else-if="trimmedQuery && resolvedResults.length === 0" class="ov-docs-search-empty">- No results found.+ {{ searchCopy.empty.noResults }}</p><p v-else-if="!trimmedQuery" class="ov-docs-search-empty">- Type a query to search the current language docs.+ {{ searchCopy.empty.initial }}</p><template v-else><adiff --git a/docs/.vitepress/theme/openviking-search-i18n.test.ts b/docs/.vitepress/theme/openviking-search-i18n.test.tsnew file mode 100644index 000000000..ed17c3d5f--- /dev/null+++ b/docs/.vitepress/theme/openviking-search-i18n.test.ts@@ -0,0 +1,27 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import { searchCopyForLocale } from './openviking-search-i18n.ts'++test('returns Chinese search UI copy for zh docs', () => {+ const copy = searchCopyForLocale('zh')++ assert.equal(copy.trigger, '搜索文档')+ assert.equal(copy.compactTrigger, '搜索')+ assert.equal(copy.inputLabel, '搜索 OpenViking 文档')+ assert.equal(copy.modes.semantic.label, '语义搜索')+ assert.equal(copy.modes.keyword.placeholder, '搜索文档中的精确词句')+ assert.equal(copy.empty.noResults, '未找到相关结果。')+ assert.equal(copy.notice('timeout', 2), 'OpenViking 搜索超时。正在显示本地文档结果。')+ assert.equal(copy.notice('rate_limited', 0), 'OpenViking 搜索请求过多。未找到本地结果。')+})++test('keeps English search UI copy as the default locale', () => {+ const copy = searchCopyForLocale('en')++ assert.equal(copy.trigger, 'Search docs')+ assert.equal(copy.compactTrigger, 'Search')+ assert.equal(copy.inputLabel, 'Search OpenViking docs')+ assert.equal(copy.modes.semantic.label, 'Semantic')+ assert.equal(copy.empty.initial, 'Type a query to search the current language docs.')+})diff --git a/docs/.vitepress/theme/openviking-search-i18n.ts b/docs/.vitepress/theme/openviking-search-i18n.tsnew file mode 100644index 000000000..8434e8d69--- /dev/null+++ b/docs/.vitepress/theme/openviking-search-i18n.ts@@ -0,0 +1,109 @@+import type { SearchLocale, SearchMode } from './openviking-search-results'++export type RemoteSearchFailureReason = 'rate_limited' | 'timeout' | 'unavailable'++type ModeCopy = {+ label: string+ placeholder: string+}++type SearchCopy = {+ compactTrigger: string+ dialogLabel: string+ empty: {+ initial: string+ loading: string+ noResults: string+ }+ inputLabel: string+ modeLabel: string+ modeOptionsLabel: string+ modes: Record<SearchMode, ModeCopy>+ notice: (reason: RemoteSearchFailureReason, localResultCount: number) => string+ trigger: string+}++const searchCopy: Record<SearchLocale, SearchCopy> = {+ en: {+ compactTrigger: 'Search',+ dialogLabel: 'OpenViking docs search',+ empty: {+ initial: 'Type a query to search the current language docs.',+ loading: 'Searching...',+ noResults: 'No results found.'+ },+ inputLabel: 'Search OpenViking docs',+ modeLabel: 'Search mode',+ modeOptionsLabel: 'Search mode options',+ modes: {+ file: {+ label: 'File',+ placeholder: 'Find docs by path or filename'+ },+ keyword: {+ label: 'Keyword',+ placeholder: 'Search exact words in the docs'+ },+ semantic: {+ label: 'Semantic',+ placeholder: 'Ask a question about the docs'+ }+ },+ notice: (reason, localResultCount) => {+ const prefix =+ reason === 'rate_limited'+ ? 'OpenViking search is rate limited.'+ : reason === 'timeout'+ ? 'OpenViking search timed out.'+ : 'OpenViking search is unavailable.'++ return localResultCount > 0+ ? `${prefix} Showing local docs results.`+ : `${prefix} No local results found.`+ },+ trigger: 'Search docs'+ },+ zh: {+ compactTrigger: '搜索',+ dialogLabel: 'OpenViking 文档搜索',+ empty: {+ initial: '输入关键词,搜索当前语言的文档。',+ loading: '搜索中...',+ noResults: '未找到相关结果。'+ },+ inputLabel: '搜索 OpenViking 文档',+ modeLabel: '搜索模式',+ modeOptionsLabel: '搜索模式选项',+ modes: {+ file: {+ label: '文件搜索',+ placeholder: '按路径或文件名查找文档'+ },+ keyword: {+ label: '关键词搜索',+ placeholder: '搜索文档中的精确词句'+ },+ semantic: {+ label: '语义搜索',+ placeholder: '询问文档内容'+ }+ },+ notice: (reason, localResultCount) => {+ const prefix =+ reason === 'rate_limited'+ ? 'OpenViking 搜索请求过多。'+ : reason === 'timeout'+ ? 'OpenViking 搜索超时。'+ : 'OpenViking 搜索暂不可用。'++ return localResultCount > 0+ ? `${prefix}正在显示本地文档结果。`+ : `${prefix}未找到本地结果。`+ },+ trigger: '搜索文档'+ }+}++export function searchCopyForLocale(locale: SearchLocale) {+ return searchCopy[locale] ?? searchCopy.en+}diff --git a/docs/.vitepress/theme/openviking-search-results.test.ts b/docs/.vitepress/theme/openviking-search-results.test.tsnew file mode 100644index 000000000..6e7ba1677--- /dev/null+++ b/docs/.vitepress/theme/openviking-search-results.test.ts@@ -0,0 +1,53 @@+import assert from 'node:assert/strict'+import test from 'node:test'++import {+ enrichSearchResultsWithLocalTitles,+ localizeSearchResultTitles+} from './openviking-search-results.ts'++test('uses the localized docs index title for Chinese remote results', () => {+ const results = enrichSearchResultsWithLocalTitles(+ [+ {+ relativePath: 'agent-integrations/08-community-plugins.md',+ snippet: '这是一份面向 OpenViking 使用者的社区插件参考文档。',+ title: 'Community Plugins',+ url: '/zh/agent-integrations/08-community-plugins'+ }+ ],+ [+ {+ locale: 'zh',+ path: 'zh/agent-integrations/08-community-plugins.md',+ text: '社区插件',+ title: '社区插件',+ url: '/zh/agent-integrations/08-community-plugins'+ }+ ],+ 'zh'+ )++ assert.equal(results[0].title, '社区插件')+})++test('keeps remote results when local title lookup fails', async () => {+ const remoteResults = [+ {+ relativePath: 'agent-integrations/08-community-plugins.md',+ snippet: 'remote snippet',+ title: 'Community Plugins',+ url: '/zh/agent-integrations/08-community-plugins'+ }+ ]++ const results = await localizeSearchResultTitles(+ remoteResults,+ 'zh',+ async () => {+ throw new Error('local index unavailable')+ }+ )++ assert.deepEqual(results, remoteResults)+})diff --git a/docs/.vitepress/theme/openviking-search-results.ts b/docs/.vitepress/theme/openviking-search-results.tsnew file mode 100644index 000000000..2af890d0f--- /dev/null+++ b/docs/.vitepress/theme/openviking-search-results.ts@@ -0,0 +1,124 @@+export type SearchLocale = 'en' | 'zh'+export type SearchMode = 'semantic' | 'keyword' | 'file'++export type DocsIndexRecord = {+ locale: SearchLocale+ path: string+ text: string+ title: string+ url: string+}++export type DocsSearchResult = {+ line?: number | null+ mode?: SearchMode+ relativePath?: string+ score?: number | null+ snippet?: string+ title?: string+ uri?: string+ url?: string+}++type LocalIndexLoader = () => Promise<DocsIndexRecord[]>++export async function localizeSearchResultTitles(+ results: DocsSearchResult[],+ locale: SearchLocale,+ loadLocalIndex: LocalIndexLoader+) {+ try {+ const localIndex = await loadLocalIndex()+ return enrichSearchResultsWithLocalTitles(results, localIndex, locale)+ } catch {+ return results+ }+}++export function enrichSearchResultsWithLocalTitles(+ results: DocsSearchResult[],+ localIndex: DocsIndexRecord[],+ locale: SearchLocale+) {+ const titleByKey = buildLocalTitleLookup(localIndex, locale)++ return results.map((result) => {+ const title = localizedTitleForResult(result, titleByKey, locale)+ return title && title !== result.title ? { ...result, title } : result+ })+}++function buildLocalTitleLookup(localIndex: DocsIndexRecord[], locale: SearchLocale) {+ const titleByKey = new Map<string, string>()++ for (const record of localIndex) {+ if (record.locale !== locale || !record.title) continue++ for (const key of localRecordKeys(record, locale)) {+ titleByKey.set(key, record.title)+ }+ }++ return titleByKey+}++function localizedTitleForResult(+ result: DocsSearchResult,+ titleByKey: Map<string, string>,+ locale: SearchLocale+) {+ for (const key of resultKeys(result, locale)) {+ const title = titleByKey.get(key)+ if (title) return title+ }++ return result.title+}++function localRecordKeys(record: DocsIndexRecord, locale: SearchLocale) {+ return [+ normalizeDocsUrl(record.url),+ normalizeLocalizedPath(record.path, locale),+ normalizeDocsUrl(urlFromRelativePath(record.path, locale))+ ].filter(Boolean)+}++function resultKeys(result: DocsSearchResult, locale: SearchLocale) {+ return [+ normalizeDocsUrl(result.url),+ normalizeLocalizedPath(result.relativePath, locale),+ normalizeDocsUrl(urlFromRelativePath(result.relativePath, locale)),+ normalizeDocsUrl(urlFromVikingUri(result.uri))+ ].filter(Boolean)+}++function normalizeDocsUrl(value: string | undefined) {+ if (!value) return ''++ const pathname = value.replace(/^https?:\/\/[^/]+/, '').split(/[?#]/, 1)[0]+ return `/${pathname.replace(/^\/+/, '')}`.replace(/\/index$/, '')+}++function normalizeLocalizedPath(value: string | undefined, locale: SearchLocale) {+ if (!value) return ''++ return value+ .replace(/^\/+/, '')+ .replace(/^docs\//, '')+ .replace(new RegExp(`^${locale}/`), '')+ .replace(/(?:\/index)?\.mdx?$/, '')+}++function urlFromRelativePath(value: string | undefined, locale: SearchLocale) {+ const normalizedPath = normalizeLocalizedPath(value, locale)+ return normalizedPath ? `/${locale}/${normalizedPath}` : ''+}++function urlFromVikingUri(value: string | undefined) {+ if (!value) return ''++ const match = value.match(/\/docs\/(en|zh)\/(.+)$/)+ if (!match) return ''++ return `/${match[1]}/${match[2].replace(/(?:\/index)?\.mdx?$/, '')}`+}diff --git a/docs/package.json b/docs/package.jsonindex ce1d28f05..d7d42f56f 100644--- a/docs/package.json+++ b/docs/package.json@@ -6,7 +6,8 @@"scripts": {"docs:dev": "vitepress dev . --host 0.0.0.0","docs:build": "vitepress build .",- "docs:preview": "vitepress preview . --host 0.0.0.0"+ "docs:preview": "vitepress preview . --host 0.0.0.0",+ "test:search": "node --experimental-strip-types --test .vitepress/theme/openviking-search-*.test.ts"},"devDependencies": {"vitepress": "1.6.4"