模块 `index` — 文档索引（RAG）

🟢 该模块为个人/组织构建本地文档索引，并通过两种方式提供给智能体：通过钩子 rag 的自动上下文，以及通过工具 index_tool 的显式搜索。来源为服务器上的文件夹和云盘（Yandex.Disk）。该模块为 dual-transport：同一份代码既可作为 linked-crate 运行，也可作为原生 DLL（lean）运行。

搜索引擎为 n-gram 位签名（char+word 3-gram）：先在 popcount 上快速召回，然后按文本进行精确重排。无需模型/嵌入。

提供内容

内容	标识符	描述
工具	`kind: index_tool`	`sources`, `search`, `open`, `status`, `sync`, `add_folder`, `remove`, `enable/disable`, `connect`
钩子	`kind: rag`（选项 `index_db`）	README 钩子读取索引并将片段注入每个请求
智能体	`index-demo`	演示智能体 + 落地页 `/ext/index-demo/`
存储	DuckDB	`data/plugins/index.db`（plugin data_dir）

该模块默认启用（id index）：它被编译为 DLL，放入 plugins/，并通过 config/plugins.yaml 加载（参见“构建与部署”）。

来源

服务器上的文件夹（`type: local`）

服务器上的绝对路径，必须位于 security.index.allowed_roots 内（为空 = 允许任意路径，限制为 sandbox agent_os.Fs）。根路径（/、C:\）被禁止。

kind: index_tool
name: index
yandex_tool: yandex_disk_idx   # какой yandex_tool использовать в connect

添加：index {operation:"add_folder", path:"D:/docs", source:"docs"}。

Yandex.Disk

通过 OAuth 登录（参见“Yandex.Disk”），然后 index {operation:"connect", ...} 和 sync。Disk 文件被下载并提取文本（文本 — 内联，二进制 — 通过外部转换器），然后构建签名。

操作 `index_tool`

操作	参数	作用
`sources`	—	来源列表和状态（`вкл`/`выкл`）+ `allowed_roots`
`add_folder`	`path`, `source`	注册服务器文件夹
`remove`	`source`	删除来源及其所有文档
`enable` / `disable`	`source`	暂停/恢复而不删除
`connect`	`source`, `code?`	Yandex.Disk 的 OAuth（见下文）
`sync` / `build`	`source`	启动索引（后台）
`status`	—	`Документов: N; единиц: M` + `allowed_roots`
`search`	`query`, `limit?`	两阶段搜索（所有者 = 用户）
`open`	`uri`	文档/单元的全文

按索引的钩子 `rag`

kind: rag
name: docs_rag
index_db: data/plugins/index.db   # читать индекс, а не архив
top_k: 5
notice: "Найдено {{count}} фрагментов из базы документов."

如果设置了 index_db，钩子会按索引进行两阶段搜索，并严格按所有者限制选取（user:<ctx.user_id>）。没有 index_db 时 — 为原先的按 BM25 归档的模式。

Yandex.Disk：登录

在 https://oauth.yandex.ru 创建 OAuth 应用（权限 Yandex.Disk REST API：cloud_api:disk.read/write/info），将 YANDEX_OAUTH_CLIENT_ID 和 YANDEX_OAUTH_CLIENT_SECRET 放入 .env。
注册 Redirect URI（https；对于本地接受 http://127.0.0.1:3000/v1/yandex/callback），在 oauth.redirect_uri 工具中设置相同的值。
index {operation:"connect", source:"my_disk", tool:"yandex_disk_idx"} — 将返回链接；确认后 — 服务器自行将代码换取令牌（GET /v1/yandex/callback，无需复制代码）。
index {operation:"sync", source:"my_disk"} → status。

每用户令牌： oauth.token_file 支持 {user} — 会代入经过清理的 user_id，每个用户有自己的 refresh 令牌和自己的会话。示例：data/yandex-oauth/{user}/disk_token.json。

配置

来源位置 — 要么修改 server.yaml，要么通过 add_folder/connect 动态设置（存储在数据库中）。服务器端 allow-list：

# server.yaml
security:
  index:
    allowed_roots: []     # абсолютные префиксы; пусто = как разрешит Fs sandbox

构建与部署

Lean-DLL：scripts/build-module-dlls.ps1（或 .sh）→ target/modules/<profile>/。
加载：在 config/plugins.yaml 中写入一行（plugins: [ … agent_os_index.dll ]）。
发行版：scripts/build_distrib.* 编译并将 DLL 放入 plugins/； config-starter/plugins.yaml 会将其拾取。
模块在 dual-transport 列表中（30-dll-ready-modules.md）。

演示智能体

index-demo（config/agents/index-demo/）— index_tool + yandex_disk_idx + 钩子 docs_rag + 落地页 /ext/index-demo/。智能体的指令引导入门流程：先询问要索引什么，然后连接来源并同步。

模块 index — 文档索引（RAG）