# 架构设计

## 总览
- `server.py`: MCP 工具注册与服务入口（FastMCP）
- `config.py`: 运行时配置加载与目录保证
- `logging_conf.py`: JSON 日志配置与滚动文件输出
- `chunkio.py`: 大文件的分片读/写/行索引/偏移到行号估算
- `search.py`: 流式正则与字面量搜索
- `indexer.py`: SQLite 倒排索引的构建与查询
- `locks.py`: 文件写入锁（基于 fcntl）

## 关键流程
- 读取：流式分块 + 边界处理，返回偏移与行号信息
- 写入：覆盖（随机写）、追加（末尾）、插入（临时文件原子替换）
- 搜索：跨块携带余量避免边界遗漏；近似行号估计
- 行索引：每 step 行记录偏移，加速行号估算
- 倒排索引：按分词规则入库（`postings`），支持增量与前缀查询

## 增量索引策略
- 记录尾部快照（offset/line），追加时直接续写
- 检测非追加修改（偏移不匹配）则执行全量重建

## 日志策略
- 控制台（JSON）与文件（旋转），避免污染 STDIO 数据通道
- 工具均记录关键入参与返回元信息，便于审计与调试
- 支持可选 `ctx` 参数在工具层传递调用上下文（仅用于日志追踪，不影响功能）