本地 RAG
本目录提供项目文档的本地 RAG 索引脚本，主要供 Agent 在执行任务前后检索项目上下文使用。它不是新的人工阅读入口；开发者仍按 AGENTS.md、docs/README.md 和 docs/project-memory/ 阅读项目文档。
项目默认不安装 RAG 运行时依赖，也不把 LanceDB、Transformers.js 或本地模型写入根 package.json。
运行时依赖
RAG 运行时依赖安装在 gitignored 的 .rag/runtime/，模型缓存和向量库也都在 .rag/ 下。
Agent 需要启用 RAG 检索时，应先询问用户是否安装本地依赖。用户确认后执行：
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，适合中英文混合文档。
npm run rag:index
小样本 smoke：
npm run rag:index -- --limit-files 3
只查看分片，不加载模型：
npm run rag:index -- --limit-files 3 --dry-run
搜索
默认输出 Agent 上下文包，包含来源、分数、候选上下文和使用规则：
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8
可限制上下文包大小：
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --limit 8 --max-chars 8000
可输出结构化格式，便于 Agent 或其它工具解析：
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format json
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format jsonl
如只想看短摘要，可使用旧式文本结果：
npm run rag:search -- --query "SpacetimeDB schema 变更默认值" --format text
Agent 使用规则：
- 把 RAG 输出视为候选上下文，不直接当作最终事实。
- 需要精确改代码或文档时，仍要打开对应源文件核对。
- 来源冲突时，以当前代码和最新
docs/为准。
索引范围
索引范围由 scripts/rag/rag-config.json 配置，默认包含：
AGENTS.mdCONTEXT.md，如果存在docs/project-memory/docs/
.codex/ 是 Codex 工具目录，不作为项目知识库索引源。