搜索与知识
搜索是 ⌘K 搜索面板、agent 的 search 工具、MCP 和 CLI 共用的一套契约。目录中每个 role: search 操作都是一个搜索源,aidy 的知识索引是另一个名为 knowledge 的搜索源。
搜索操作是效果为 read 的 GET,带必填查询参数 q 和可选的 limit:
"/api/vms/search": { "get": { "x-aidy": { "name": "search_vms", "role": "search" } }}GET /api/vms/search?q=gpu&limit=10{ "hits": [ { "type": "vm", "id": "vm-42", "title": "gpu-train-01", "excerpt": "Running · 8 × H100 · cn-beijing-a", "url": "/console/instance/vm-42", "updatedAt": "2026-11-19T08:00:00Z" } ]}SearchHit
Section titled “SearchHit”| 字段 | 含义 |
|---|---|
type |
必填。简短的类型(vm、item、doc),用于分组和过滤。 |
id |
必填。在同一类型内唯一。 |
title |
必填。 |
excerpt |
可选的纯文本,最多 300 个字符。匹配处可以用 «…» 包起来。 |
url |
必填。产品内的路径,或外部内容的绝对 URL。 |
updatedAt |
可选的 RFC 3339 时间。 |
content |
可选的纯文本,最多 4000 个字符:给模型看的正文段落。 |
有了 content,模型就能根据正文回答,而不只是 300 个字符的摘要。aidy 通过 search 工具和 MCP 把它交给模型,并从 GET /aidy/v0/search 和引用中去掉它,因为这些是给人看的。
aidy 以用户身份调用每个搜索源,所以结果已经按用户权限过滤。最佳结果放在最前。limit 默认 10,最大 50。Python kit 提供 SearchHit 和 SearchResponse 模型;TypeScript 的 SearchHit 在 @aidy-dev/spec/search 中。
GET /aidy/v0/search?q=gpu&limit=10&types=vm,docaidy 并行查询所有搜索源,每个源有自己的超时,返回:
{ "hits": [{ "source": "search_vms", "type": "vm", "id": "vm-42", "title": "gpu-train-01", "url": "/console/instance/vm-42" }], "failed": [{ "source": "search_chat", "code": "timeout" }]}结果用 k = 60 的倒数排名融合(RRF)合并。每条结果的得分是返回它的各个源上 1 / (60 + rank) 之和。只看各源给出的排名,因此不同源的分数无需可比。每条结果都标明自己的 source。
失败的源列在 failed 中,错误码为 timeout、http_<status> 或 invalid_response。它不会让整个搜索失败:聊天索引慢了,服务器和文档的结果仍然完整。
每个源的超时默认 2 秒,最大 10 秒:在搜索操作的 x-aidy 中设置 timeoutSeconds(更大的值会被视为目录错误),或在配置的 SearchSource 上设置 timeoutMs(默认 2000,最大 10 000)。
"x-aidy": { "name": "search_chat", "role": "search", "timeoutSeconds": 5 }agent 的 search 工具
Section titled “agent 的 search 工具”模型在你的操作旁边看到一个内置的 search 工具,它返回与联邦检索接口相同的结果,外加 content,并在整个运行内从 1 开始编号为 n。当回答以 [1]、[2] 引用结果时,运行会发出一个 CUSTOM 事件:
{ "type": "CUSTOM", "name": "aidy.citation", "value": { "messageId": "msg_…", "citations": [ { "n": 1, "hit": { "source": "knowledge", "type": "doc", "id": "docs/stop/0", "title": "Stopping servers", "url": "/docs/stop" } } ] }}每个被引用的结果都放在回答所写的编号 n 下,因此 [11] 或 [2][4] 也能对应到正确的结果,客户端可以据此渲染脚注。MCP 客户端也能用同一个 search 工具,CLI 中则是 aidy search "gpu box"。
@aidy-dev/knowledge 把 Markdown 文档索引到任意 SqlDriver(Postgres、SQLite、Cloudflare D1)上的集合中,并作为名为 knowledge 的搜索源。基于它的回答同样通过 aidy.citation 事件给出引用。
import { createKnowledge } from '@aidy-dev/knowledge';import { sqliteDriver } from '@aidy-dev/sql/sqlite';
const knowledge = createKnowledge({ driver: sqliteDriver('knowledge.sqlite') });await knowledge.migrate();
await knowledge.ingest('docs', [ { id: 'stop', title: 'Stopping servers', url: '/docs/stop', markdown: '# Stopping servers\n\n## Forced stop\n\nA forced stop skips the guest shutdown.', },]);
createAidy({ // ... sources: [knowledge.source({ collections: (identity) => ['docs', `manuals/${identity.tenant}`] })],});- 文档按 h1 到 h3 标题切分,过长的小节再按段落、句子切分。每个分块的 URL 是文档 URL 加标题锚点(标题上显式写的
{#id},否则为 GitHub 风格的 slug),标题为文档标题 › 标题路径。每条结果以content携带分块正文。 - 检索以词法为主(SQLite 和 D1 上用 BM25,Postgres 上用
ts_rank),并对 CJK 文本建立二元组索引,中文无需空格也能匹配。提供embed函数时,向量相似度会与词法排名融合,同样使用 k = 60 的 RRF。 collections(identity)决定每个用户能搜索什么,例如公共文档加上本租户的手册。ingest会跳过未变化的文档,所以可以在每次部署时重新运行。
导入、向量和限制的细节见知识指南。
- 身份
- AG-UI profile:
aidy.citation - React 指南:
SearchPalette