当有已固定或本地代码库、需要结构化调用与函数边界上下文提升代…

在 pinned 快照后或 MODE-OFF live 代码库上可选构建结构化索引，提供 find_callers/get_function_boundary 等查询来排序和补充 grep 发现，但绝不替代 grep。

适用场景

解决思路

1. 运行命令 `/mantis-structural-index`，可选参数由 orchestrator 传入 `--snapshot_root`/`--snapshot_id`/`--state_root`；若全部缺失则进入 MODE-OFF/legacy 模式：从当前目录读源码，把索引写到 `./workspace/kb/structural_index/`。
2. 读取 `workspace/.mantis_state.json` 以取得 `active_snapshot` 做 provenance 检查和 snapshot-aware rebuild。
3. 读取 `workspace/kb/structural_index/manifest.json` 的 `snapshot_id`，作为复用匹配的首要检查。
4. 若 manifest 缺失，读取 `workspace/kb/structural_index.jsonl` 的 provenance header 做向后兼容检查。
5. 读取 `workspace/kb/structural_index/units/` 做内容寻址缓存，用于增量 unit 复用。
6. 读取 `workspace/kb/structural_index/native/` 及其 sidecar `provenance.json`，识别预构建索引附件与元数据。
7. 通过生成的 helper 脚本解析 `CODE_ROOT` 下所有源码文件。
8. 写入 `workspace/kb/structural_index/manifest.json`，作为 STATE-RELATIVE 的原子提交点，必须最后写入。
9. 写入 `workspace/kb/structural_index/catalog.sqlite`，作为查询优化的服务存储。
10. 写入 `workspace/kb/structural_index/units/`，作为内容寻址不可变 unit 输出。
11. 写入 `workspace/kb/structural_index/shards/`，作为大型语料的分区服务数据。
12. 写入 `workspace/kb/structural_index/native/`，作为预构建索引附件（SCIP、Kythe、LSIF）。
13. 写入 `workspace/kb/structural_index/tmp/`，作为构建期间临时对象目录。
14. 写入 `workspace/kb/structural_index.jsonl`，作为兼容指针；低于阈值时导出完整 JSONL。
15. 写入 `workspace/helpers/build_structural_index.py`，作为 builder helper 脚本。
16. 写入 `workspace/helpers/query_structural_index.py`，作为 query helper 脚本。
17. 若 `CODE_ROOT` 未解析且没有可读 `active_snapshot`，则对当前目录构建，并把 `snapshot_id` 设为 `unknown`；不要跳过，这是 standalone-efficiency 场景。
18. 该技能在未被 caller 调用前返回空索引；工具不可用或源码无法解析时也返回空索引，绝不失败。
19. 保证幂等：对 `CODE_ROOT` 只读，只写 STATE-RELATIVE 路径；相同 `CODE_ROOT` 和 `SNAPSHOT_ID` 时复用已有索引，MODE-OFF 除外总是重建；单个 semantic unit 在 content-addressed cache key 匹配时跨快照复用。
20. Step 0.0：若该技能从不读取目标源码（report、calibrate、reflect），则作为 FINDINGS-ONLY stage，跳过步骤 2-6；仍从 state 读 `active_snapshot` 做 provenance/annotation；不要仅因 code root 未设置而停止。
21. Step 0.1a：若本次调用传入 `--target_root`，则 `CODE_ROOT = --target_root`，它权威并覆盖 `SNAPSHOT_ROOT` 与 state fallback，用于 caller 交给你的已准备树，例如 patched shadow。
22. Step 0.1b：否则若传入 `--snapshot_root` 或 `SNAPSHOT_ROOT`，使用它。
23. Step 0.1c：否则读取 `state_root/workspace/.mantis_state.json`，其中 `state_root` 来自 `--state_root`，否则为当前目录下的 `./workspace/...`，取得 `active_snapshot.root`、`.snapshot_id`、`.snapshot_pinned`。
24. Step 0.1d：否则没有参数且没有可读 `active_snapshot` 时，`CODE_ROOT = current directory`，`snapshot_pinned = false`，进入 MODE-OFF；不要停止。
25. Step 0.2：仅当 `snapshot_pinned` 为 true 且没有走路径 1a 时做 SENTINEL CHECK：验证 `CODE_ROOT/.mantis_snapshot_id` 存在且等于 `SNAPSHOT_ID`；缺失或不同则 STOP 并报 `snapshot sentinel mismatch`；`--target_root` 树故意可变，sentinel-EXEMPT。
26. Step 0.3：处理 PATH FIELDS；SNAPSHOT-RELATIVE 在 `CODE_ROOT` 下读，包括 code_paths 条目和 plan target_files 里的文件路径；只去掉末尾的 `:<digits>`；包含 `://` 的 code_paths 条目是 URL/endpoint，不是文件读取；非 `<existing-path>:<integer>` 形式的是 non-source LOCATOR，只检查 artifact/symbol 存在，跳过所有 line-range 和 line-existence 逻辑。
27. Step 0.3：STATE-RELATIVE 在 `state_root/workspace` 下读写，绝不在 `CODE_ROOT` 前缀，包括 `kb_references`、`repro_file_path`、`reattack_file_path`、helper scripts、report files、所有 state/findings JSON。
28. Step 0.4：`snapshot_pinned` 为 true 时绝不在 `CODE_ROOT` 下写；任何会编译、生成或写产物的命令必须在 PRIVATE SHADOW copy 中运行，例如从 `CODE_ROOT` 执行 `mktemp -d`，不能使用 `cwd=CODE_ROOT`；只读检查可以 cd 进 `CODE_ROOT`。
29. Step 0.5：VCS-METADATA CARVE-OUT：history-log 提取和任何 VCS diff/blame 命令在 LIVE repository root 运行，该 root 仍有 `.git/.hg/.repo`，不要用 `CODE_ROOT`，因为 snapshot copy 会剥离 VCS 元数据；不要仅因 `CODE_ROOT` 没有 `.git/.hg/.repo` 而停止。
30. Step 0.6：每条 shell 命令使用 ABSOLUTE paths，并在该调用中设置自己的工作目录；不要假设工作目录在调用之间保持。
31. Step 1.1：最先做 MODE-OFF check；若 `SNAPSHOT_ID` 为 `unknown` 或缺失，总是重建，不要复用之前的 `unknown` 索引，因为 live tree 可变且 `unknown` 不是 freshness 信号；直接跳到 Step 2，未变的单个 unit 仍可命中 content-addressed cache。
32. Step 1.2：若 `workspace/kb/structural_index/manifest.json` 存在，读取其 `snapshot_id` 字段。
33. Step 1.3：若 `snapshot_id` 匹配当前 `SNAPSHOT_ID` 且 `SNAPSHOT_ID` 不是 `unknown`，立即复用索引并 STOP；不要调用 Step 2、探测 backend 或写构建脚本；这限制重试/crash-resume 成本。
34. Step 1.4：若 `manifest.json` 缺失但 `workspace/kb/structural_index.jsonl` 存在，读取其 provenance header 的 `_provenance`、`snapshot_id` keys；若 `snapshot_id` 匹配且不是 `unknown`，复用并 STOP；否则继续重建。
35. Step 1.5：若 `SNAPSHOT_ID` 不同，继续重建 Steps 2-5；增量复用前，在重建 semantic unit 前检查 `units/` 是否有 content-addressed cache hit；命中则复用 unit 输出而不重新抽取。
36. Step 2：把代码库分区为 semantic units；对每个 unit 使用 capability-based、per-partition 决策选择本环境中最精确可用 backend，而不是单一全局 ladder；helper 每分区探测并选择最高可用 tier。
37. Step 2 Tier 1：若存在匹配当前 `snapshot_id` 或 `root_fingerprint` 的预构建 SCIP/LSIF/Kythe/clangd-static/remote index，选择 precision 为 `semantic` 的 backend；最精确，提供完整类型感知交叉引用、call hierarchy、hover/signature 数据。
38. Step 2 Tier 2：若存在 `compile_commands.json`、build context 或 typechecker，选择 compiler/typechecker-backed extractor，precision 为 `typecheck`；提供类型准确 symbol resolution 和 call edges。
39. Step 2 Tier 3：若存在 `tree-sitter`、`ast-grep` 或语言专用 parser，选择 language-aware AST extraction，precision 为 `ast`；进行完整 AST 解析，得到 function boundaries、call expressions、signatures。
40. Step 2 Tier 4：若 `ctags` 或等价工具在 `PATH` 上，选择 symbol-only extraction，precision 为 `symbol-only`；仅 symbol table，包括 function definitions 和 locations，无 call graph；call-site 提取在已知 function boundaries 内用 lightweight regex pass。
41. Step 2 Tier 5：使用 heuristic fallback，precision 为 `heuristic`；用 Python stdlib regex pass 扫描源码文件，以语言无关启发式识别 function definitions 和 call patterns；精度较低但零依赖。
42. Step 2 Tier 6：使用 coverage-only manifest + lexical fallback，precision 为 `coverage-only`；用 grep，不写 structural index，manifest 记录 `status: "empty"`；消费者回退 grep-based discovery。
43. Step 2 Native Probing：在评估 per-partition backend 前，探测 `workspace/kb/structural_index/native/` 和子目录 `native/{scip,lsif,kythe}/` 的预构建索引文件。
44. Step 2 Native Snapshot Declaration：native 格式不在二进制 payload 内嵌 snapshot identity，因此预构建索引必须用 sidecar `provenance.json` 声明目标 snapshot，位于 `workspace/kb/structural_index/native/provenance.json` 或 `native/<kind>/provenance.json`。
45. Step 2 Native Provenance Schema：该 manifest 包含 attachments 数组，每个附件含 `kind`、`path`、`snapshot_id`、`root_fingerprint`、`language`、`indexer`、`precision`、`files`；匹配条件是声明的 `snapshot_id` 等于 `SNAPSHOT_ID`（当 `SNAPSHOT_ID != unknown`）或 `root_fingerprint` 匹配 workspace 计算出的 root fingerprint。
46. Step 2 Native Files 缺失规则：若 `files` 数组缺失或为空，把 native index 视为不直接覆盖任何单个文件；记录到 `manifest.native_indexes` 但不要更新 `coverage` rows，所有文件 fall through 到更低 tier。
47. Step 2 Record-and-Defer：纯 Python 无依赖解析 raw binary native indexes（例如 SCIP protobuf）代价高且复杂；Option A builder scripts 必须检测匹配的预构建 native indexes，把条目记录到 `manifest.native_indexes`，并为 provenance manifest 中所有文件设置 `coverage` 表 `backend`，例如 `scip` 或 `scip-clangd`。
48. Step 2 Deferred 状态：若 `catalog.sqlite` 未被 native index 的 symbols 填充，且 raw binary 延迟给 harness/MCP readers，设置 `coverage.status = "deferred"` 和 `precision = "deferred"`，并令 `indexed_files = 0`；防止 query helper 把未摄入 partition 声称成 `semantic` precision 下的 authoritative empty，确保消费者运行强制 grep fallback。
49. Step 2 Indexed 状态：当 `catalog.sqlite` 已被填充，例如通过 Option B pre-ingestion 或 `scip-to-sqlite`，设置 `precision = "semantic"` 和 `status = "indexed"`。
50. Step 2 LSP 规则：LSP 不等价于 SCIP/LSIF；LSP 是交互协议，workspace state 可能 partial 或 mutable；仅当 server 能证明 snapshot identity 且完整 workspace coverage 时才使用；运行中的 language server 不自动算 `semantic` backend。
51. Step 2 SCIP merging：SCIP 明确允许合并不同 precision indexers 的互补信息；其格式记录 indexer version 和 per-document language metadata；builder 可以在同一 catalog 内合并多个 indexer 的结果，例如 Go 的 SCIP index 加 Python 的 tree-sitter。
52. Step 2 Helper 探测：determinism 来自 runtime-generated versioned helper `build_structural_index.py`，包含 `# MANTIS_HELPER_VERSION = 5`，复用前 grep 并 regenerate；该 helper 探测并 per-partition 选择 backend；无 shipped binaries，air-gapped-safe。
53. Step 2 Deterministic Partial Coverage：在超大源码树上，全量重建可能占满 stage-0 wall-clock；用 deterministic priority queue 替代 discovery-order truncation。
54. Step 2 Priority Queue 1：优先处理来自 `plan.json`（若可用）的显式 target files 和 symbols。
55. Step 2 Priority Queue 2：优先处理来自 Block E diff 的 changed units 和 existing catalog 中 known reverse dependencies。
56. Step 2 Priority Queue 3：优先处理 tier 1+2 units 的 containing packages/modules 和 direct imports。
57. Step 2 Priority Queue 4：其余 units 按 normalized path order 处理。
58. Step 2 Bounds：对队列应用确定性 `max_units`（默认 10000）或 `max_source_bytes`（默认 500MB）界限；把 deferred units 持久化到 manifest，便于另一个 invocation resume；状态为 `complete`、`partial`、`empty`、`failed`。
59. Step 2 No Callers 解释：只有当相关 partition 是 complete、snapshot-matched、covered 且 semantically precise 时，消费者才可强解释 `no callers`；否则回答 `no indexed callers`，然后运行现有 lexical fallback；索引是 HINT-only，部分覆盖安全，grep 仍权威。
60. Step 3：使用两个 runtime-generated helpers；二者遵循 grep-and-regenerate 模式：复用前 grep 第一行版本标记，若缺失或整数不同则 REGENERATE。
61. Step 3 Builder 1：把 builder 写到 `workspace/helpers/build_structural_index.py`；第一行必须精确为 `# MANTIS_HELPER_VERSION = 5`；复用已有 helper 前 grep 其前几行确认该 marker；缺失或不同整数则 REGENERATE。
62. Step 3 Builder 2：builder 把代码库分区为 semantic units，计算 content-addressed cache keys，检查 `units/` 复用，选择 per-partition backend，抽取 symbols + edges，并把结果写入 `catalog.sqlite`。
63. Step 3 Builder 3 Symbols：builder 必须抽取 `symbol_id`、`name`、`qualified_name`、`namespace`、`language`、`file_path`、`start_line`、`end_line`、`kind`、`signature`、`backend`、`precision`。
64. Step 3 Builder 3 Call Edges：builder 必须抽取 `caller_id`、`callee_id`、`callee_name`、`file_path`、`line`、`edge_kind`。
65. Step 3 Builder 3 Function Boundaries：builder 必须抽取 `symbol_id`、`file_path`、`start_line`、`end_line`、`signature`、`language`。
66. Step 3 Builder 3 Coverage：builder 必须抽取 `file_path`、`indexed`、`backend`、`precision`、`unit_cache_key`、`status`。
67. Step 3 Builder 4：builder 最后写 manifest（Step 4）和 compatibility pointer。
68. Step 3 Builder 5：builder 必须使用 ABSOLUTE paths 并设置自己的工作目录；`snapshot_pinned` 为 true 时不得在 `CODE_ROOT` 下写任何东西。
69. Step 3 Builder 5 Sidecar Redirect：会产生 sidecar 文件的 backend 必须重定向到 STATE-RELATIVE 路径，例如 `ctags -f <state>/helpers/tags`、`cscope -f <state>/helpers/cscope.out`、`CLANGD_INDEX_STORAGE=<state>/helpers/`；对运行中 server 的只读 LSP/SCIP 查询无需重定向。
70. Step 3 Query Helper 1：把 query helper 写到 `workspace/helpers/query_structural_index.py`；第一行必须精确为 `# MANTIS_HELPER_VERSION = 5`；复用已有 helper 前 grep 该版本标记；缺失或不同整数则 REGENERATE。
71. Step 3 Query Helper 2：query helper 提供针对 `catalog.sqlite` 的有界、分页操作，或针对 remote endpoint 的相同 API；它本身就是 consumption contract。
72. Step 3 Query Helper 3：若 `catalog.sqlite` 缺失但 `structural_index.jsonl` 存在，query helper 回退到线性扫描 JSONL，较慢但可用；若两者都缺失，返回空结果并设置 `coverage.partition_status = "empty"`。
73. Step 4.1：先把 manifest 写到 `workspace/kb/structural_index/tmp/manifest.json`，再原子 rename 到 `workspace/kb/structural_index/manifest.json`；这是 atomic commit point，manifest 在所有 units、catalog、coverage 数据写完后最后写入。
74. Step 4.2：写 compatibility pointer 到 `workspace/kb/structural_index.jsonl`，它是 STATE-RELATIVE，绝不在 `CODE_ROOT` 下；低于可配置阈值（默认 10K records）时输出完整 JSONL export，包含 provenance header 和所有 records；高于阈值时只输出 provenance header，并设置 `compat_pointer.full_export = false` 与 `compat_pointer.symbol_count`；大型消费者必须使用 query interface。
75. Step 4.3：manifest 的 `provider.backend_versions` 字段记录每种语言用了哪个 backend，例如 `go -> scip-clangd, precision=semantic`、`python -> tree-sitter, precision=ast`，让消费者知道 precision level。
76. Step 4.4：中断的构建会在 `tmp/` 留下未引用临时对象，但不会损坏上一次发布索引；resume 时检查 `manifest.json` 的 status 和 `snapshot_id`（Step 1）。
77. Step 5.1：返回 `manifest.json`、`catalog.sqlite`、query helper 的路径，并包含 summary：unit count、symbol count、call-edge count、backends used、coverage status。
78. Step 5.2：若索引为空（无可用工具或找不到 source files），通知 caller：`Structural index is empty — structural context unavailable.`
79. Step 5.3：不要直接通知用户；该技能由 harness、planner 或 researcher 作为 sub-agent 调用。
80. 定义 on-disk layout：`workspace/kb/structural_index/` 下有 `manifest.json`、`catalog.sqlite`、`units/`、`shards/`、`native/`、`tmp/`；`workspace/helpers/` 下有 `build_structural_index.py` 和 `query_structural_index.py`；`workspace/kb/structural_index.jsonl` 是 compatibility pointer。
81. 定义 manifest schema 字段：`schema_version`、`snapshot_id`、`root_fingerprint`、`status`、`provider`、`units`、`coverage`、`shards`、`deferred_units`、`native_indexes`、`baseline`、`overlay`、`compat_pointer`、`created_at`、`build_duration_ms`。
82. 定义 SQLite catalog schema 表：`schema_meta`、`symbols`、`call_edges`、`function_boundaries`、`coverage`、`unit_cache`、`deferred_units`。
83. 为 SQLite catalog 建 indexes：`idx_symbols_name`、`idx_symbols_qualified`、`idx_symbols_file`、`idx_symbols_lang`、`idx_edges_caller`、`idx_edges_callee`、`idx_edges_callee_name`、`idx_edges_file`、`idx_boundaries_file`、`idx_coverage_status`、`idx_deferred_priority`，确保 caller/callee 两个方向都有索引。
84. Partitioning：当 symbols 超过 500K 或 edges 超过 2M，按 `lang:{language}:bucket:{NN}` 的 stable hash 把数据分片到 `shards/` 下的 shard SQLite 文件；每个 shard 使用相同 schema；query helper 根据 manifest 把查询路由到正确 shard。
85. Content-Addressed Cache Key：`cache_key = sha256(schema_version + extractor_name@version + language + compile_context_digest + ordered_input_content_digests + dependency_or_interface_digest)`。
86. Cache Key 关键规则：`snapshot_id` 不放入 cache key，只放 provenance；这允许在 commits、branches、snapshots 之间复用相同 units。
87. Canonical Symbol IDs：native IDs 使用 `scip:{symbol}`、`kythe:{uri}`、`clangd:{usr}`；无 semantic backend 时使用 fallback ID：`fallback:{language}:{file_path}:{sha256(qualified_name|start_line|signature)[:16]}`。
88. Fallback ID 目的：区分 namespaces、overloads、methods、local functions，以及跨 languages 或 repositories 的 duplicate names。
89. Edge Kinds：明确分开且绝不静默合并：`direct` 表示静态解析到已知 symbol 的调用；`indirect` 表示 function pointer、closure、callback；`virtual` 表示 virtual method dispatch，运行时解析；`macro` 表示 macro expansion 引入的调用；`unresolved` 表示找到 callee name 但未解析出 symbol_id。
90. Per-Language Semantic Units：C/C++ 使用 Compilation unit，compile context 是 `compile_commands.json` entry，dependency digest 是 transitively headers interfaces 的 sha256。
91. Per-Language Semantic Units：Go 使用 Package，compile context 是 `go.mod + build tags`，dependency digest 是 imported packages 的 exported API 的 sha256。
92. Per-Language Semantic Units：Rust 使用 Crate，compile context 是 `Cargo.toml + features`，dependency digest 是 extern crate signatures 的 sha256。
93. Per-Language Semantic Units：Java/Kotlin 使用 Compiler batch，compile context 是 module path + classpath，dependency digest 是 imported class signatures 的 sha256。
94. Per-Language Semantic Units：TypeScript 使用 Project，compile context 是 `tsconfig.json`，dependency digest 是 imported module type declarations 的 sha256。
95. Per-Language Semantic Units：Fallback 使用 Individual file，compile context 为 None，dependency digest 为空字符串。
96. Fallback Granularity Rule：对于 fallback tier（regex、AST parser 或无语言 build system 的 lightweight crawler），每个 source file 必须作为自己的独立 semantic unit；绝不要把多个 source files 捆绑成一个 fallback unit。
97. Fallback Granularity 原因：per-file unit isolation 对 content-addressed cache 效率关键；未来快照中一个文件变化时只使该文件 unit 失效，所有未变文件命中 cache，`reused = N-1`。
98. Baseline + Delta Overlay：Static baseline 在 CI 中为完整 snapshot 构建一次。
99. Baseline + Delta Overlay：Incremental cache 使用不可变 unit outputs，可跨 snapshots 复用。
100. Baseline + Delta Overlay：Delta overlay 在本地索引 changed/target files，并 layered over baseline。
101. Baseline + Delta Overlay：Remote serving 在本地构建全局索引代价过高时可选。
102. Baseline + Delta Overlay 查询：query helper 合并 baseline + overlay 结果；同一文件 overlay symbols 取代 baseline symbols；manifest 记录 `provider.kind = "baseline+overlay"`，并含 baseline manifest reference 和 overlay unit count。
103. Compatibility JSONL Export：旧 `structural_index.jsonl` 只作为兼容导出保留，不是 query contract；低于阈值（默认 10K records）输出完整 JSONL export；高于阈值只写 provenance pointer；大型消费者必须使用 query interface。
104. Compatibility JSONL Export 结构：Line 1 是 provenance header，包含 `_provenance=true`、`snapshot_id`、`tool`；Lines 2+ 是 structural records，每行有 `_type` discriminator。
105. Compatibility JSONL Record Types：`function` 表示带 boundary 和 signature 的 function definition，关键字段是 `key`、`start_line`、`end_line`、`signature`、`calls`；`call_edge` 表示 caller 到 callee 在 `file:line` 的调用，关键字段是 `caller`、`callee`、`file`、`line`。
106. Snapshot Safety 1：当 snapshot pinned 时，从 pinned `CODE_ROOT` 构建 structural index，确保它反映 pipeline 正在分析的精确 bytes，而不是 live tree。
107. Snapshot Safety 2：复用匹配；若 `manifest.json` 已带当前 `SNAPSHOT_ID` 且 `SNAPSHOT_ID` 不是 `unknown`，复用它，不要重建；MODE-OFF 总是重建；`SNAPSHOT_ID` 不同或 `unknown` 时重建；单个 units 仍可从 content-addressed cache 复用；这限制重试/crash-resume 成本。
108. Snapshot Safety 3：Manifest atomicity；manifest 通过从 `tmp/` 原子 rename 最后写入；中断构建留下未引用临时对象但不会损坏上次发布索引；resume 时检查 `manifest.json` status 和 `snapshot_id`。
109. Snapshot Safety 4：HALT 模式下的 STALE flag；若 `snapshot_pinned` 为 false，索引可能从 unpinned `CODE_ROOT` 构建，但必须标记为 potentially stale；消费者把 structural hints 视为 advisory。
110. Snapshot Safety 5：MODE-OFF 时 build，不要 skip；当 `active_snapshot` 缺失时，对 current directory 构建，provenance 的 `snapshot_id` 设为 `unknown`；这是 standalone-efficiency 场景，索引对 researcher/planner 仍有用；不要仅因 snapshot 缺失而返回空索引。
111. Consumption Contract Query 1：`resolve_symbol(name, language?, file?, namespace?)` 返回 `{results, total, ambiguous, coverage}`；返回所有匹配，不对 ambiguous symbols 做静默选择；caller 必须先 disambiguate，再调用 `find_callers`/`find_callees`。
112. Consumption Contract Query 2：`find_callers(symbol_id, limit=100, offset=0)` 返回 `{results, total, has_more, coverage}`；有界分页查找 caller；每个结果携带 `precision`、`backend`、`edge_kind`；空结果携带 `coverage.partition_status`。
113. Consumption Contract Query 3：`find_callees(symbol_id, limit=100, offset=0)` 返回与 `find_callers` 相同形状的结果。
114. Consumption Contract Query 4：`get_function_boundary(file, line)` 返回 `{symbol_id, start_line, end_line, signature, precision, backend}`。
115. Consumption Contract Query 5：`get_coverage(file?)` 返回 `{total_files, indexed_files, failed, deferred, partition_status, backends_used}`。
116. Query Key Properties：结果有界且分页，防止把整个索引加载进内存；图遍历前显式做 name resolution，避免 ambiguous symbols 静默选择；每个结果都附 precision 和 backend；空结果附 coverage；local 和 remote providers 使用相同 operations，remote 通过 `MANTIS_STRUCTURAL_INDEX_URL` 环境变量或 manifest `provider.kind = "remote"` 指定。
117. Coverage on Empty Results：`partition_status=complete` 表示所有文件已索引，回答 `No indexed callers`，但仍按 HINT-only 规则运行 grep。
118. Coverage on Empty Results：`partition_status=partial` 表示部分文件 deferred 或 failed，回答 `Not fully indexed`，必须运行 grep fallback。
119. Coverage on Empty Results：`partition_status=empty` 表示无 backend 可用，回答 `Not indexed`，必须运行 grep fallback。
120. Coverage on Empty Results：`partition_status=failed` 表示 backend 尝试过但失败，回答 `Index failed`，必须运行 grep fallback。
121. mantis-plan 用法：用 structural index query helper 做 function-level dependency fan-out；规划调查时调用 `resolve_symbol()` 再调用 `find_callers()`，识别所有调用目标函数的函数，从而把审计集扩大到单文件分析之外。
122. mantis-plan 边界：structural index 决定 investigations 的 ORDER，即按 call-graph centrality 决定先审计哪些函数，绝不决定 MEMBERSHIP；它可以扩大审计集，安全 over-reporting，但绝不能 REMOVE 或 drop 文件；planner 现有逻辑仍是 membership floor。
123. mantis-researcher Wave 1 Rapid Triage：先对 function name 做 repo-wide grep，建立 exhaustive 的 candidate call-sites 集，这是 mandatory floor；再用 query helper 的 `resolve_symbol` 然后 `find_callers` 来 RANK 和 prioritize 先审计哪些 call-sites，因为索引能区分 actual calls 与 comments/strings/variable names；审计两者结果的 union；索引可能漏 macro-based calls、function pointers、dynamic dispatch，所以 grep 仍是 floor。
124. mantis-researcher Wave 2 Deep Audit：用 `get_function_boundary(file, line)` 从 enclosing function 开始，按需扩展到 callers/callees/file 来获得跨函数上下文；这节省 context 同时保持覆盖。
125. mantis-researcher fallback：若 structural index 缺失或为空，回退到 grep-based discovery；structural index 只是 coverage HINT，提高审计质量但绝不必需。
126. Safety 1 Agnostic：不存在任何必需依赖；no-tool、parse-fail、not-invoked 都得到 empty index 并回退 grep，行为与今天 byte-for-byte 相同；它在 Pass Lifecycle Contract 中是 optional；不符合的 harness 直接跳过。
127. Safety 2 HINT-only / union / never MEMBERSHIP：消费者审计与 grep 的 union；索引漏掉的 symbol 仍必须可被 exhaustive sweep 到达；structural index 决定 ORDER，绝不决定 MEMBERSHIP；query contract 强制 `find_callers` 返回 HINTs，绝不返回 authoritative membership，消费者必须 union with grep。
128. Safety 3 No verdicts：不能产生 verdicts，不触碰 findings；不能违反 INV-1，也不能自己 drop 一个 finding。
129. Safety 4 Narrow scope：只做 source cross-reference；binary/build-derived reachability（例如判断是否编译进 production）明确 out of scope，这是 dev customization，不属于该 skill，因为 absence-from-a-build 可能隐藏 real finding（INV-2）；不要把 build-derived reachability 并入该 skill。
130. Reference blueprint：参考 `mantis-pipeline-adapter/references/mantis-structural-index.md`；它是 stub，指向该 SKILL.md 作为单一事实来源，不要在其中复制 spec 内容。

适用边界 · 注意事项

• 不要用于 findings 分析、打补丁或报告生成。
• 不要用于 binary/build-derived reachability，例如判断代码是否编译进生产；absence-from-build 可能隐藏真实 finding。
• 没有源码或没有可用工具时不要期望结构化结果；应返回空索引并回退 grep，而不是失败或阻止流程。