用途:在快照固定后、首个代码阅读分析阶段前运行,从源码构建内容寻址的语义单元索引,为发现阶段提供结构化上下文,补充但不替代基于 grep 的调用点发现。
主要能力:按分区选择后端,精度从高到低包括快照匹配的 SCIP/LSIF/Kythe/clangd 静态或远程索引、编译器/类型检查器提取、语言感知 AST 提取、仅符号提取、启发式回退,以及仅覆盖清单加 grep 回退。提供 find_callers(symbol)、get_function_boundary(file, line) 和调用点感知。索引由独立语义编译单元组成,持久化为 manifest 加 SQLite 目录,并通过有界查询助手暴露。
使用方式:命令为 /mantis-structural-index,可选参数 --snapshot_root、--snapshot_id、--state_root,均由编排器提供。全部缺省时进入 MODE-OFF/legacy 模式,从当前目录读取源码,索引写入 ./workspace/kb/structural_index/。构建器写入 workspace/helpers/build_structural_index.py,查询助手写入 workspace/helpers/query_structural_index.py,两者首行须为 # MANTIS_HELPER_VERSION = 5,复用前需 grep 校验,否则重新生成。
幂等与限制:对 CODE_ROOT 只读,仅写 STATE-RELATIVE 路径;相同 CODE_ROOT 与 SNAPSHOT_ID 重跑会复用现有索引,MODE-OFF 下始终重建。未接线时返回空索引且不会失败。索引仅为提示,部分覆盖安全,grep 仍具权威性;只有分区完整、快照匹配、已覆盖且语义精确时,才可强解读“无调用者”。