# 索引与检索规则

本技能基于规则做文档检索，不依赖大模型，结果可解释。

## 索引范围

- README（经 readme 接口）
- 以下目录中的文档文件：根目录、`docs/`、`doc/`、`.gitlink/`、`wiki/`
- 文档扩展名：`.md` / `.markdown` / `.rst` / `.txt`
- 默认最多索引 20 个文档（`--max-files` 可调）

## 文档切分

按 Markdown 标题（`#` ~ `######`）把文档切分为段落，每段记录：所属文档、标题、标题层级、正文。

## 检索算法

1. 把查询拆为关键词：
   - 英文按 `[A-Za-z0-9_]+` 切词；
   - 中文额外做 2-gram 切分（如「如何安装」→「如何」「何安」「安装」），兼顾中文无空格分词。
2. 对每个段落计分：
   - 正文 + 标题中每出现一次关键词 +1；
   - 关键词命中**标题** 额外 +5（标题更能代表段落主题）。
3. 按分数降序返回前 N 段（默认 5），附 300 字摘要。

## FAQ 提取

识别形似问题的标题并提取问答对，判定规则（命中任一）：

- 标题含 `?` 或 `？`
- 标题以 `Q:` / `Q ` / `how` / `what` / `why` / `when` / `如何` / `怎么` / `为什么` / `是否` 开头

## 文档地图

按文档归类所有标题，保留层级缩进，呈现仓库文档的整体结构。

## 局限

- 基于关键词命中，不做语义向量检索；对同义词/近义表达的召回有限。
- 仅索引文本类文档，不索引代码文件。
