跳转到内容

搜索与知识

搜索是 ⌘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"
}
]
}
字段 含义
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,doc

aidy 并行查询所有搜索源,每个源有自己的超时,返回:

{
"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 }

模型在你的操作旁边看到一个内置的 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 会跳过未变化的文档,所以可以在每次部署时重新运行。

导入、向量和限制的细节见知识指南。