# 本地 RAG

本目录提供项目文档的本地 RAG 索引脚本，主要供 Agent 在执行任务前后检索项目上下文使用。它不是新的人工阅读入口；开发者仍按 `AGENTS.md`、`docs/README.md` 和 `docs/project-memory/` 阅读项目文档。

项目默认不安装 RAG 运行时依赖，也不把 LanceDB、Transformers.js 或本地模型写入根 `package.json`。

## 运行时依赖

RAG 运行时依赖安装在 gitignored 的 `.rag/runtime/`，模型缓存和向量库也都在 `.rag/` 下。

Agent 需要启用 RAG 检索时，应先询问用户是否安装本地依赖。用户确认后执行：

```bash
mkdir -p .rag/runtime
npm init -y --prefix .rag/runtime
npm install --prefix .rag/runtime @lancedb/lancedb@0.30.0 @huggingface/transformers@4.2.0
```

不要把这些依赖加入根 `package.json`。

## 索引

首次运行会下载本地 embedding 模型到 `.rag/models/`。默认模型为 `Xenova/multilingual-e5-small`，适合中英文混合文档。

```bash
npm run rag:index
```

小样本 smoke：

```bash
npm run rag:index -- --limit-files 3
```

只查看分片，不加载模型：

```bash
npm run rag:index -- --limit-files 3 --dry-run
```

## 搜索

默认输出 Agent 上下文包，包含来源、分数、候选上下文和使用规则：

```bash
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8
```

可限制上下文包大小：

```bash
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8 --max-chars 8000
```

可输出结构化格式，便于 Agent 或其它工具解析：

```bash
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format json
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format jsonl
```

如只想看短摘要，可使用旧式文本结果：

```bash
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format text
```

Agent 使用规则：

- 把 RAG 输出视为候选上下文，不直接当作最终事实。
- 需要精确改代码或文档时，仍要打开对应源文件核对。
- 来源冲突时，以当前代码和最新 `docs/` 为准。

## 索引范围

索引范围由 `scripts/rag/rag-config.json` 配置，默认包含：

- `AGENTS.md`
- `CONTEXT.md`，如果存在
- `docs/project-memory/`
- `docs/`

`.hermes/` 是 Hermes 工具目录，不作为项目知识库索引源。