---
title: "Поиск по базе знаний | Busymate AI"
description: "Поиск с клавиатуры по той же базе знаний, которую использует чат."
---
# Поиск по базе знаний | Busymate AI

Source: https://busymate.ai/ru/docs/guides/knowledge-widget
The knowledge widget searches the **same index your chat uses**. It does not crawl or embed your site a second time. Configure it in **Console → Knowledge search**. Changes save automatically; **Undo** writes the previous settings back. A revision conflict asks you to reload instead of overwriting another editor's changes. No chat publish is needed.

## Before enabling

Review the Page index and the coverage note in Knowledge search. Select all indexed knowledge, published knowledge, or connected sources. Enabling this product makes those sources searchable by visitors. Excluded pages remain excluded by the existing retrieval reader.

Add your site's exact origin to the workspace's allowed embed origins. The knowledge widget uses that same origin list, with its own enable switch. An unknown origin cannot frame it. There is no wildcard framing policy.

## Install

Copy the snippet shown by your Console. Its hostname belongs to your workspace:

```html
<script defer src="https://YOUR-WORKSPACE.busymate.ai/kb/v1.js"
  data-hotkey="mod+k" data-slash="false" data-trigger="keyboard"></script>
```

The loader installs listeners only. It does not fetch configuration, create an iframe, read storage, or download the palette until the first trigger. An optional floating button is created locally. Recopy the snippet after changing trigger settings: fetching them before opening would violate the zero-eager-network contract.

## Triggers and JavaScript

`mod+k` means Command+K on Apple platforms and Control+K elsewhere. Custom chords use `mod`, `ctrl`, `meta`, `alt`, and `shift`, followed by one letter or digit; for example `alt+shift+p`. `/` is optional. Keyboard shortcuts are ignored while composing text or editing an input, textarea, select, contenteditable element, or textbox.

```html
<button type="button" data-busymate-kb-trigger>Search documentation</button>
<input data-busymate-kb-trigger aria-label="Search documentation">
```

```javascript
window.BusymateKB.open("billing");
window.BusymateKB.close();
window.BusymateKB.configure({ hotkey: "alt+k", slash: true, trigger: "floating", label: "Search" });
```

`open()` takes an optional string, the query to start with (up to 500 characters). Any other value, such as the `event` an inline handler passes, opens the palette empty.

The palette opens centred over the page, which is dimmed and blurred behind it; at 640 px and below it is a full-height sheet. The modal and its stylesheet live in a shadow root on a `<busymate-kb>` element the loader appends to your page, so your site's CSS resets and `dialog` rules never reach it and its rules never reach your page. With nothing typed it offers **Actions** (Search the docs, Ask your mate), **Go to** (your site's top indexed pages, shallowest first) and **Recent searches**, whose last row is **Clear recent searches**. Typing shows results grouped by page with snippets, the cited answer as a row of its own group when enabled (Enter opens its source), and **Ask your mate about this** as the last row; until the first results arrive, Enter keeps searching rather than handing off. Use ↑/↓ to move, Tab and Shift+Tab to jump between groups, Enter to run the highlighted row (a result opens in a new tab, a Go to destination opens in the page), and Escape to close. Every row, the answer and Clear included, is an option of one listbox, so screen readers reach all of them from the search field. The native modal keeps focus inside the palette and returns it to the opener on close. Recent searches are stored locally; a browser that blocks storage still supports search.

## Results and answers

Hybrid retrieval combines lexical and semantic ranking over the existing index. Results are grouped by page: a page whose title, top heading or address names the query ranks first, a page shows at most two sections, and a copy of a page in another language gives way to the copy in the language the search names (`lang`), else to the unprefixed copy. Each row is titled by its section and shows the sentence that matched. A match by meaning alone, with none of the query's words, needs strong similarity to appear. Results without a safe HTTP(S) page URL are omitted. The optional short answer quotes an excerpt and links its source; it needs both the query's words and a close match in meaning, so weak, lexical-only or meaning-only evidence produces a refusal, not an invented answer. Search failures are distinct from zero matches.

**Ask your mate about this** opens the workspace chat with the query prefilled for review. It does not automatically send a message.

## API and MCP

The browser palette calls the tenant host:

```http
POST /api/v1/kb/search
Content-Type: application/json
Accept: text/event-stream

{"query":"billing"}
```

Anonymous scope comes from the serving host, never `tenant_id` in the body. Admission is shared across server replicas: 30 requests per visitor IP bucket per minute, and 600 per tenant per minute. No IP address or query text is stored in the events trail. A refused budget returns `429` with `Retry-After`; retrieval or configuration outages return `503`.

With `Accept: application/json`, search returns `{query, results, answer, refused, searchId}`. Each result has `id`, `title` (the section), `url` (the page, with a text fragment to the matched words where there is one), `snippet`, `group` (the page title), `score`, `pageUrl` (the page itself; group by this, since two pages can share a title), `section` (null for a page's introduction) and `highlights` (`[start, end]` offsets of the query's words in `snippet`). The score is relevance relative to the first result, which scores 1; it never increases down the list. An answer is `{text, citation}` or null. SSE sends `results`, optional `answer` chunks, then `done`. An optional `lang` in the request body (the page's language, which the loader sends for you) picks the matching copy of a page.

Workspace API keys use the existing REST/MCP facade and its `{ok, data}` response envelope. `search_knowledge`, `get_kb_widget_config`, and `set_kb_widget_config` are the corresponding MCP tools. Management calls are tenant-authorized; writes require confirmation and an expected `revision`. REST configuration is `GET /api/v1/kb/config` and `POST /api/v1/kb/config`. Never expose an API key in the install tag.

The public palette exposes `search_knowledge` as a WebMCP page tool when the platform's WebMCP provider is enabled and the browser supports it. It uses the same HTTP endpoint and limits.

## Appearance, language and measurement

The palette follows the page it opens on. Its theme is, in order: the page's own explicit choice (`data-theme="light|dark"` on `<html>`, or a `dark` / `light` class on it, the way most site toggles pin it), then the **Appearance** setting in Console (`Light` or `Dark`; `System` means "follow the page"), then the operating system. The Console setting is read by the palette itself every time it opens, so a change in Console applies at once; nothing about appearance is written into the snippet, and there is nothing to recopy. Its language is the page's `<html lang>`, then the `data-lang` on the install tag, then the visitor's browser preference. Both are read when the palette opens, so the first paint already matches, and both are re-applied without a reload if the page changes them while the palette is open: the loader watches the `<html>` attributes and the `storage` event, so a theme toggle or a language switch on the page reaches the open palette at once. A page that sets its language in JavaScript without touching `<html>` can pass it directly:

```javascript
window.BusymateKB.configure({ lang: "de" });
```

The palette uses the app's semantic theme tokens and tenant branding. The host page's CSS does not cross the iframe boundary.

The closed events are `kb.search.performed`, `kb.result.clicked`, `kb.zero_results`, and `kb.handoff_to_chat`. Each may carry a `surface` attribute, `marketing` or `docs`, naming which of this site's own pages opened the palette; a palette on your site never sends it. Authenticated Console previews and management MCP/API searches are excluded.

## On this site

This site runs the same widget, bound to the platform workspace and driven by its own Console settings: the **Search** field in the header (an icon on phones) and the configured shortcut open the palette on every page, including this documentation. Its **Go to** group lists this site's own navigation. Nothing beyond the loader is downloaded until you open it. **Ask your mate about this** hands the query to the chat launcher in the corner of the page, prefilled for review; **Ask your mate** with nothing typed simply opens the launcher. The metric catalogue reserves `kb_searches`, `kb_zero_result_rate`, `kb_click_through`, and `kb_handoffs`; their aggregate readers and Insights pages are phase 2, so unavailable totals are never displayed as zero.

This guide has the standard Markdown twin at `/docs/guides/knowledge-widget.md`.