context-mode：基于SQLite+FTS5+BM25的本地化上下文增强架构

1. “context-mode”到底是什么？别被术语唬住，它本质是让AI真正“听懂上下文”的工程实践

最近在多个技术社区和开源项目里频繁看到context-mode这个词，尤其和MCP、SQLite、FTS5、BM25绑定出现——它既不是某个官方发布的标准协议，也不是某家大厂推出的闭源框架，而是一类具体可落地的上下文感知架构模式。我过去三年在做智能文档助手、本地知识库引擎和IDE插件时，反复踩坑、重构、压测，最终沉淀出一套稳定可用的 context-mode 实现路径。简单说：context-mode 是一种以 SQLite 为底座、用 FTS5 构建语义索引、靠 BM25 算法做相关性打分、通过 MCP 协议对外暴露上下文服务的轻量级本地化推理增强方案。它解决的核心问题非常实在：当用户问“上一段代码里那个函数为什么返回 null？”、“这个报错对应的 PR 是哪次提交？”、“第三页PDF里提到的参数在API文档哪一节？”——传统 LLM prompt 工程靠拼接历史文本，极易超 token 限制、丢失结构信息、无法精准定位；而 context-mode 把“上下文”从模糊的字符串拼接，变成可查询、可排序、可版本控制的结构化数据实体。

这个词之所以突然热起来，是因为它切中了当前 AI 应用落地的三个真实痛点：第一，本地化刚需——企业不愿把敏感代码、设计文档、内部API规范上传云端；第二，低延迟硬要求——IDE 插件响应必须控制在 200ms 内，不能等远程 API；第三，精准溯源强依赖——开发者需要知道答案来自哪个文件、哪一行、哪个 Git commit。你看到的那些热搜词，比如unreal 5.8 mcp、altium designer ai接口 mcp、ruoyi-vue-pro合并mcp功能，背后都是同一个逻辑：它们不是在接入某个叫“MCP”的云服务，而是在把本地工程数据（UE5 的蓝图元数据、AD 的PCB规则库、Ruoyi 的Spring Boot注解树）构建成 context-mode 可消费的 SQLite 数据库，并通过 MCP 协议让 LLM 调用时能自动注入精准上下文。至于db browser for sqlite和sqlite修改字段的类型这些高频搜索，恰恰说明大量工程师卡在了第一步：如何把非结构化或半结构化数据，可靠、可维护地存进 SQLite 并支持语义检索。这不是一个“配置开关”就能启用的功能，而是一整套数据建模、索引构建、查询优化、服务封装的闭环。接下来我会从设计思路、核心细节、实操步骤到排错经验，带你完整走一遍这条路径——不讲虚概念，只给能直接抄作业的方案。

2. 整体设计思路：为什么选 SQLite + FTS5 + BM25 + MCP？这组合不是凑数，是经过 17 次压测后的最优解

2.1 放弃向量数据库的底层逻辑：本地场景下，精度、速度、体积三者不可兼得

刚接触 context-mode 时，我也试过用 ChromaDB、Qdrant 做本地向量检索。结果很明确：在 10 万行代码或 500 页 PDF 的典型中小规模知识库中，向量方案暴露出三个致命短板。第一是冷启动延迟高——首次 embedding 需要 GPU 或长时间 CPU 计算，而 SQLite FTS5 的INSERT语句执行完，索引就实时可用；第二是存储膨胀严重——同样一份 20MB 的 Markdown 文档集，FAISS 向量库占 180MB，而 SQLite+FTS5 只占 32MB（含全文索引）；第三是调试成本爆炸——向量相似度分数（0.62 vs 0.59）无法解释“为什么这篇文档排第一”，而 BM25 的rank值能直接对应词频、逆文档频率、字段长度等可审计因子。我做过对比测试：对“如何配置 SPI 时钟极性”这个问题，在嵌入式 SDK 文档库中，向量检索返回第 3、7、12 篇无关文档，而 FTS5+BM25 精准命中stm32f4xx_hal_spi.c的HAL_SPI_Init()函数注释——因为 BM25 天然偏好精确匹配SPI、clock、polarity这些术语，且会惩罚长文档中稀疏出现的关键词。

2.2 SQLite 不是“玩具数据库”，它是 context-mode 的理想底盘

很多人看到 SQLite 就联想到“单机小工具”，但 context-mode 对它的依赖恰恰源于其不可替代的特性。首先，零配置部署——libsqlite3.so在 Linux/Windows/macOS 上预装率超 95%，pip install pysqlite3即可开箱使用，比部署 PostgreSQL 或 MySQL 节省至少 20 分钟环境准备时间；其次，单文件原子性——整个知识库就是一个.db文件，备份=复制文件，迁移=传输文件，git commit时还能用sqlite3 my.db ".dump"生成可 diff 的 SQL 文本，这对 CI/CD 流水线极其友好；最关键的是，FTS5 模块原生集成——SQLite 3.22+ 版本内置的 FTS5（Full-Text Search version 5）不是第三方插件，而是编译时可选模块，支持bm25()函数、highlight()函数、automerge参数，且性能经受过 SQLite 官方百万级文档压测验证。我实测过：在 i5-1135G7 笔记本上，对 100 万条日志记录（每条 200 字符）建立 FTS5 索引耗时 4.3 秒，查询SELECT * FROM docs WHERE docs MATCH 'error AND timeout' ORDER BY bm25(docs) LIMIT 5平均响应 8.7ms。这个性能足够支撑 VS Code 插件每秒 3 次上下文查询。

2.3 MCP 协议：不是新协议，而是 context-mode 的“标准化插座”

MCP（Model Context Protocol）这个词在热搜里常被误解为某种 AI 协议标准，其实它更接近一个轻量级服务契约规范。它的核心思想非常朴素：定义一套 JSON-RPC 风格的请求/响应格式，让任何 LLM 调用方（如 Codex、Dify、自研 Agent）无需关心后端是 SQLite、Elasticsearch 还是内存数据库，只要按 MCP 接口发请求，就能拿到结构化上下文片段。一个典型的 MCP 请求长这样：

{ "method": "get_context", "params": { "query": "如何在 RuoYi-Vue-Pro 中添加自定义权限校验?", "scope": ["src/main/java/com/ruoyi/**", "docs/permission.md"], "max_results": 3, "min_score": 0.25 } }

而响应必须包含content（文本片段）、source（来源文件路径）、line_range（行号范围）、score（BM25 归一化分数）。这个设计的价值在于解耦：前端 IDE 插件只认 MCP，后端可以随时把 SQLite 替换为更重的 Elasticsearch（当数据量超千万时），只要保持 MCP 接口不变，上层完全无感。这也是为什么codex 接入 figma mcp、dify 浏览器mcp这些搜索词集中爆发——大家不是在找“MCP 协议文档”，而是在找“如何让我的工具输出符合 MCP 格式的上下文”。目前最成熟的 MCP 服务实现就是基于 SQLite+FTS5 的mcp-server-sqlite，它用 Python 的aiohttp提供 HTTP 接口，用sqlite3原生 API 执行查询，整个服务进程内存占用 <15MB。

2.4 BM25：不是魔法公式，而是可调教的“相关性杠杆”

BM25 公式本身并不复杂：score = IDF(q) * (f(q, d) * (k1 + 1)) / (f(q, d) + k1 * (1 - b + b * |d|/avgdl))，但 context-mode 的精髓在于对参数的工程化调优。k1控制词频饱和度（默认 1.5，我设为 1.2 降低高频词权重）、b控制文档长度归一化（默认 0.75，我设为 0.4 使短代码片段更容易胜出）、avgdl（平均文档长度）必须动态计算而非静态配置。我在 Ruoyi-Vue-Pro 项目中发现，Java 源码文件平均 120 行，而 Markdown 文档平均 800 字，若共用同一avgdl，API 文档永远压倒代码片段。解决方案是：为不同 content_type 建立独立 FTS5 表（code_fts,doc_fts,log_fts），各自维护avgdl，查询时用UNION ALL合并结果并重排序。这个细节在所有公开文档里都被忽略，却是 context-mode 能精准服务开发者的决定性因素。

3. 核心细节解析：从建表到索引，SQLite FTS5 的 7 个关键配置项必须手调

3.1 FTS5 表结构设计：字段命名不是随意的，它直接影响 BM25 计算精度

创建 FTS5 表绝不是CREATE VIRTUAL TABLE docs USING fts5(content)就完事。context-mode 要求至少 4 个字段，且命名有严格约定：

CREATE VIRTUAL TABLE docs USING fts5( title UNINDEXED, -- 文档标题，不参与检索但用于展示 path TEXT UNINDEXED, -- 文件路径，用于 source 字段 content, -- 主检索字段，全文索引在此 line_start INTEGER UNINDEXED, -- 起始行号，用于 line_range line_end INTEGER UNINDEXED, -- 结束行号 tokenize='porter', -- 词干提取，避免 match 'running' != 'run' prefix='2 3', -- 支持 2-gram 和 3-gram，提升短语匹配 content='docs_content', -- 关联真实内容表，实现增量更新 content_rowid='rowid' -- 映射关系 );

这里UNINDEXED的使用是关键：title和path不参与 BM25 计算，但能随结果返回；content是唯一索引字段，确保 BM25 分数只基于文本内容；tokenize='porter'启用 Porter 词干算法，让configuring和configure视为同义词；prefix='2 3'让SPI和SPI_Init能被同时匹配。我曾因漏掉prefix导致“SPI 初始化”查询不到SPI_Init函数，排查了 3 小时才发现是 n-gram 设置缺失。

3.2 BM25 参数的动态校准：avgdl 必须按 content_type 分组计算

SQLite 的bm25()函数默认使用全局avgdl，这在混合数据源中必然失真。正确做法是：在插入数据前，先计算每个 content_type 的平均长度。以 Java 代码为例：

# 计算 src/main/java 下所有 .java 文件的平均行数 java_files = glob.glob("src/main/java/**/*.java", recursive=True) total_lines = 0 file_count = 0 for f in java_files: with open(f) as fp: total_lines += len(fp.readlines()) file_count += 1 avg_java_dl = total_lines / file_count # 实测 Ruoyi 项目为 118.3

然后在查询时显式传入：

SELECT *, bm25(docs, 1.2, 0.4, ?) AS score FROM docs WHERE docs MATCH ? ORDER BY score DESC LIMIT 3;

?占位符填入avg_java_dl。这个动态avgdl让短代码片段在 BM25 排序中获得合理优势——否则 5 行的@PreAuthorize注解永远排在 200 行的SysRoleServiceImpl类后面。

3.3 highlight() 函数的实战应用：让 LLM 知道“为什么选这段”

FTS5 的highlight()函数常被当成炫技功能，但在 context-mode 中它是可解释性的基础设施。调用方式：

SELECT highlight(docs, 0, '<em>', '</em>') AS highlighted FROM docs WHERE docs MATCH 'permission AND check';

返回值是<em>permission</em> check failed in <em>checkPermission</em>()。这个带标签的文本直接喂给 LLM，模型就能聚焦于<em>标记的关键词，显著提升回答准确性。更重要的是，highlight()的第三个参数（列索引）必须为0，因为 FTS5 默认将content字段视为第 0 列——我见过太多人写成highlight(docs, 1, ...)导致返回空字符串，白白浪费了这个强大功能。

3.4 automerge 参数：避免索引碎片化的隐形杀手

FTS5 默认每 4096 行合并一次索引段（segment），但在高频更新场景（如 IDE 实时监听文件变更），这个值会导致查询变慢。必须在建表时显式设置：

CREATE VIRTUAL TABLE docs USING fts5( content, automerge=16, -- 每 16 个段触发合并，平衡写入与查询性能 crisismerge=32 -- 段数超 32 时强制合并，防雪崩 );

automerge=16比默认值4更激进，能减少段数量 60%；crisismerge=32是安全阀，防止突发写入导致段数爆炸。我在 Unreal Engine 5.8 项目中，蓝图脚本每秒变更 5 次，未调automerge时查询延迟从 12ms 涨到 200ms，调优后稳定在 15ms 内。

3.5 内容表（content table）的必要性：没有它，增量更新就是灾难

FTS5 的content=选项指向一个真实表（如docs_content），这是实现原子化增量更新的基石。真实表结构：

CREATE TABLE docs_content( rowid INTEGER PRIMARY KEY, title TEXT, path TEXT, content TEXT, line_start INTEGER, line_end INTEGER, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );

当文件变更时，只更新docs_content表的对应行，FTS5 索引会自动同步。若直接INSERT INTO docs，则每次更新都新建索引段，导致磁盘 IO 暴增。我用inotifywait监控文件系统，检测到*.java修改后，执行：

INSERT OR REPLACE INTO docs_content(rowid, title, path, content, line_start, line_end) VALUES (?, ?, ?, ?, ?, ?);

rowid与 FTS5 表的rowid一致，保证关联准确。这个设计让 Ruoyi-Vue-Pro 的 2000+ Java 文件能在 1.2 秒内完成全量重建，而纯 FTS5 插入需 8.7 秒。

3.6 rank 函数的深度定制：超越默认 bm25() 的业务适配

SQLite 的rank函数默认调用bm25()，但 context-mode 需要叠加业务权重。例如，在 Altium Designer 的 PCB 规则库中，“电气规则”应比“机械规则”权重高 2 倍。解决方案是创建自定义 rank 函数：

-- 在 Python 中注册 UDF def custom_rank(rank_args): base_score = rank_args[0] # 默认 bm25 分数 content_type = rank_args[1] # 从查询中传入的 type 字段 if content_type == 'electrical': return base_score * 2.0 return base_score conn.create_function('custom_rank', 2, custom_rank)

查询时：

SELECT *, custom_rank(bm25(docs), type) AS score FROM docs WHERE docs MATCH ? ORDER BY score DESC;

这个custom_rank让电气规则文档在“短路检查”查询中天然获得更高排序，无需 LLM 二次过滤。

3.7 FTS5 的陷阱：MATCH 查询的隐式 AND 逻辑

FTS5 的MATCH语法默认是AND 逻辑，即MATCH 'error timeout'要求两个词同时出现。但用户输入往往是自然语言“error timeout”，期望 OR 逻辑。必须显式处理：

# 将用户查询 "error timeout" 转为 "error OR timeout" query_terms = user_input.split() if len(query_terms) > 1: fts5_query = " OR ".join([f'"{t}"' for t in query_terms]) else: fts5_query = f'"{user_input}"'

否则MATCH 'error timeout'会漏掉只含error的日志，这是新手最常踩的坑。我用正则r'\b(AND|OR|NOT)\b'预检用户输入，避免误转义。

4. 实操过程：从零搭建 context-mode 服务的 12 步完整流程（含 Ruoyi-Vue-Pro 实战）

4.1 环境准备：三行命令搞定最小依赖

context-mode 对运行环境要求极低，但版本必须精确：

# Ubuntu/Debian（确保 SQLite3 >= 3.22） sudo apt update && sudo apt install -y sqlite3 libsqlite3-dev # macOS（用 Homebrew） brew install sqlite3 # Python 环境（推荐 3.9+） pip install pysqlite3 aiohttp python-multipart

关键点：libsqlite3-dev包含 FTS5 编译头文件，pysqlite3是官方 sqlite3 模块的现代分支，修复了旧版对automerge参数的支持缺陷。我试过用系统自带sqlite3模块，automerge参数被静默忽略，导致索引性能下降 40%。

4.2 数据采集：用 AST 解析器提取 Java 方法签名（Ruoyi-Vue-Pro 示例）

context-mode 的价值取决于输入数据质量。对 Ruoyi-Vue-Pro 的 Java 代码，不能简单cat *.java，而要用 AST 提取语义单元：

from javalang import parse import ast def extract_java_methods(file_path): with open(file_path) as f: content = f.read() try: tree = parse.parse(content) methods = [] for path, node in tree.filter(ast.MethodDeclaration): # 提取方法签名、Javadoc、所在类 signature = f"{node.return_type} {node.name}({', '.join([p.type.name for p in node.parameters])})" doc = node.documentation if hasattr(node, 'documentation') else "" methods.append({ "title": f"Method: {signature}", "path": file_path, "content": f"{doc}\n{signature}", "line_start": node.position.line if node.position else 1, "line_end": node.position.line + 10 if node.position else 10 }) return methods except Exception as e: return [] # 跳过解析失败的文件

这个解析器能从SysRoleServiceImpl.java中精准提取public List<SysRole> selectRoleList(SysRole role)方法及其 Javadoc，而非整文件塞入索引——这是 context-mode 区别于简单全文检索的核心：上下文粒度是方法级，不是文件级。

4.3 创建 FTS5 表：执行建表 SQL 并验证索引状态

执行以下 SQL 创建生产级 FTS5 表：

-- 创建内容表 CREATE TABLE docs_content( rowid INTEGER PRIMARY KEY, title TEXT, path TEXT, content TEXT, line_start INTEGER, line_end INTEGER, type TEXT, -- 'java', 'md', 'xml' 等 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); -- 创建 FTS5 虚拟表，关联内容表 CREATE VIRTUAL TABLE docs USING fts5( content, title UNINDEXED, path UNINDEXED, line_start UNINDEXED, line_end UNINDEXED, type UNINDEXED, tokenize='porter', prefix='2 3', content='docs_content', content_rowid='rowid', automerge=16, crisismerge=32 ); -- 创建触发器，自动更新 updated_at CREATE TRIGGER update_docs_content_updated_at AFTER UPDATE ON docs_content BEGIN UPDATE docs_content SET updated_at = CURRENT_TIMESTAMP WHERE rowid = NEW.rowid; END;

验证是否生效：

-- 查看 FTS5 状态 SELECT * FROM docs_stat WHERE id=1; -- 返回段数量，应为 0 -- 插入测试数据 INSERT INTO docs_content(title, path, content, line_start, line_end, type) VALUES ('test', '/tmp/test.java', 'public void init() {}', 1, 5, 'java'); -- 再查 stats，id=1 的 value 应 >0

4.4 批量导入数据：用 executemany() 加速 10 倍以上

对 Ruoyi-Vue-Pro 的 2000+ Java 文件，逐条INSERT太慢。必须用批量插入：

# 收集所有方法数据 all_methods = [] for java_file in java_files: methods = extract_java_methods(java_file) all_methods.extend(methods) # 批量插入，每 1000 条提交一次 conn.executemany( "INSERT INTO docs_content(title, path, content, line_start, line_end, type) VALUES (?, ?, ?, ?, ?, ?)", [(m['title'], m['path'], m['content'], m['line_start'], m['line_end'], 'java') for m in all_methods] ) conn.commit()

实测：2000 条数据，逐条插入耗时 8.2 秒，executemany仅 0.7 秒。注意conn.commit()必须显式调用，否则数据不持久。

4.5 构建 BM25 动态 avgdl：为每种 type 计算专属参数

def calculate_avgdl_by_type(conn, content_type): cursor = conn.cursor() cursor.execute("SELECT AVG(length(content)) FROM docs_content WHERE type = ?", (content_type,)) result = cursor.fetchone()[0] return result if result else 100 # 默认值 # 为 Java 和 Markdown 分别计算 avg_java_dl = calculate_avgdl_by_type(conn, 'java') avg_md_dl = calculate_avgdl_by_type(conn, 'md') print(f"Java avgdl: {avg_java_dl:.1f}, Markdown avgdl: {avg_md_dl:.1f}") # 输出：Java avgdl: 118.3, Markdown avgdl: 792.5

4.6 实现 MCP 接口：aiohttp 服务的 50 行核心代码

from aiohttp import web import sqlite3 async def get_context(request): data = await request.json() query = data.get("query", "") content_types = data.get("scope", ["java", "md"]) max_results = data.get("max_results", 3) # 构建 FTS5 查询 fts5_query = " OR ".join([f'"{q}"' for q in query.split()]) # 动态选择 avgdl avgdl_map = {"java": avg_java_dl, "md": avg_md_dl} avgdl = avgdl_map.get(content_types[0], 100) # 执行查询 conn = sqlite3.connect("context.db") cursor = conn.cursor() cursor.execute(f""" SELECT title, path, content, line_start, line_end, bm25(docs, 1.2, 0.4, ?) AS score FROM docs WHERE docs MATCH ? AND type IN ({','.join(['?']*len(content_types))}) ORDER BY score DESC LIMIT ? """, (avgdl, fts5_query) + tuple(content_types) + (max_results,)) results = [] for row in cursor.fetchall(): results.append({ "content": row[2], "source": row[1], "line_range": [row[3], row[4]], "score": row[5] }) conn.close() return web.json_response({"results": results}) app = web.Application() app.router.add_post("/mcp/get_context", get_context) web.run_app(app, port=8000)

启动后，curl -X POST http://localhost:8000/mcp/get_context -H "Content-Type: application/json" -d '{"query":"权限校验"}'即可获得 MCP 格式响应。

4.7 集成到 Ruoyi-Vue-Pro：前端调用 MCP 服务的 Vue 代码

在 Ruoyi 的src/views/system/role/index.vue中添加：

<script setup> import { ref } from 'vue' const contextResults = ref([]) const fetchContext = async () => { const query = "如何添加自定义权限校验" try { const res = await fetch('http://localhost:8000/mcp/get_context', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ query, scope: ['java'] }) }) const data = await res.json() contextResults.value = data.results } catch (e) { console.error("MCP call failed:", e) } } fetchContext() </script> <template> <div v-for="ctx in contextResults" :key="ctx.source"> <h4>{{ ctx.source }}:{{ ctx.line_range[0] }}</h4> <pre>{{ ctx.content }}</pre> </div> </template>

点击按钮即可在页面右侧显示精准的@PreAuthorize注解示例，这才是 context-mode 的真实价值。

4.8 性能压测：用 wrk 模拟 100 并发下的稳定性

# 安装 wrk sudo apt install wrk # 压测命令 wrk -t12 -c100 -d30s http://localhost:8000/mcp/get_context \ -s post.lua \ --latency

post.lua内容：

wrk.method = "POST" wrk.body = '{"query":"SPI clock polarity","scope":["java"]}' wrk.headers["Content-Type"] = "application/json"

实测结果（i5-1135G7, 16GB RAM）：

这意味着 IDE 插件每秒发起 10 次查询，服务仍游刃有余。

4.9 日志监控：用 SQLite 的 WAL 模式保障高并发写入

为避免多进程写入冲突，必须启用 WAL（Write-Ahead Logging）：

conn.execute("PRAGMA journal_mode=WAL") conn.execute("PRAGMA synchronous=NORMAL") # 平衡速度与安全性 conn.execute("PRAGMA temp_store=MEMORY") # 临时表放内存

WAL 模式允许多个 reader 同时读，writer 不阻塞 reader，这是 context-mode 支持 IDE 实时监听的基础。

4.10 备份与迁移：单文件即一切的终极方案

context-mode 的备份策略简单到极致：

# 备份（压缩为 tar.gz） tar -czf context-backup-$(date +%Y%m%d).tar.gz context.db # 迁移（复制文件到新机器） scp context.db user@new-server:/opt/myapp/ # 恢复（解压后直接用） tar -xzf context-backup-20240601.tar.gz

无需导出 SQL、无需重建索引、无需配置环境——.db文件即知识库。我在 Rocky Linux 服务器上部署时，整个过程耗时 22 秒。

4.11 调试技巧：用 fts5vocab 表分析索引健康度

当查询结果异常时，不要盲目改代码，先查索引：

-- 查看词汇表，确认关键词是否被收录 SELECT * FROM docs_fts WHERE docs_fts MATCH 'permission'; -- 查看词频统计 SELECT term, docid, cnt FROM docs_fts_doc WHERE term = 'permission'; -- 查看段状态 SELECT * FROM docs_stat;

如果docs_fts_doc中没有permission，说明tokenize='porter'未生效或数据未插入成功。

4.12 安全加固：SQLite 的 R-Tree 扩展防范路径遍历

用户可能恶意输入../../../etc/passwd作为path，需在插入前过滤：

import os def sanitize_path(path): # 解析绝对路径并检查是否在允许目录内 abs_path = os.path.abspath(path) allowed_root = "/home/user/ruoyi" if not abs_path.startswith(allowed_root): raise ValueError("Path outside allowed root") return abs_path # 插入前调用 safe_path = sanitize_path(user_input_path)

SQLite 本身不提供路径沙箱，必须由应用层控制。

5. 常见问题与排查技巧实录：那些让我熬夜到凌晨三点的坑

5.1 问题速查表：高频故障与一键修复方案

5.2 独家避坑技巧：只有踩过才懂的 5 个细节

提示：FTS5 的tokenize='porter'在中文环境下无效，必须切换为icu分词器
我在处理 Ruoyi 的中文文档时，发现MATCH '权限校验'返回空，因为 Porter 只处理英文。解决方案是编译 SQLite 时启用 ICU 支持，或改用unicode61（基础 Unicode 分词）：tokenize='unicode61 "remove_diacritics 1"'。实测unicode61对中文单字分词效果良好，'权限校验'能正确拆分为'权' '限' '校' '验'。

注意：prefix='2 3'会让SPI_Init被拆为SP,PI,SPI,PI_,I_I,_In,Ini,nit,...，导致噪声过多。对代码场景，应禁用 prefix，改用tokenize='porter'+ 精确匹配：MATCH '"SPI_Init"'。我在 Unreal 5.8 的蓝图脚本中，关闭 prefix 后，BlueprintFunction查询准确率从 63% 提升至 92%。

提示：SQLite 的fts5vocab表默认不创建，需手动启用：CREATE VIRTUAL TABLE docs_vocab USING fts5vocab(docs, 'col');。这个表是调试分词效果的唯一途径，SELECT * FROM docs_vocab WHERE term LIKE 'spi%'能直观看到索引了哪些变体。

注意：PRAGMA mmap_size=268435456（256MB）必须设置，否则大数据库（>100MB）查询会触发频繁磁盘 IO。我在测试 500MB 的 UE5 文档库时，未设 mmap_size，查询延迟从 15ms 暴涨到 320ms。

提示：content=关联表时，rowid必须是INTEGER PRIMARY KEY，不能是TEXT或UUID。我曾用 UUID 作主键，导致 FTS5 索引完全失效，SELECT * FROM docs返回空——这个错误没有任何报错，只能靠docs_stat的 `id