需要目标代码的完整结构化分析（热点、污点、爆炸半径…

当 vivisect 第一阶段需要某目标的详细结构化数据时，用 Trailmark 建图并运行 engine.preanalysis() 输出全部四类预分析结果。

适用场景

解决思路

1. 通过 args 参数传入目标目录。
2. 先检查 trailmark 是否可用：运行 `trailmark analyze --help 2>/dev/null || uv run trailmark analyze --help 2>/dev/null`；若两条命令都不可用，报告 "trailmark is not installed" 并返回，不要执行 `pip install`、`uv pip install`、`git clone` 或任何安装命令，必须由用户自行安装。
3. 可选记录版本：运行 `trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null || true`；该命令缺失不要报错，改用下面的 API 特性探测。
4. 用 Trailmark 的 parse API 检测语言：运行 python3 脚本，先 `from trailmark.parse import detect_languages`（0.3.x 起的规范位置），若 ModuleNotFoundError 则回退 `from trailmark.query.api import detect_languages`（v0.2.x），打印 `detect_languages(sys.argv[1])` 的 JSON。
5. 若上述 import 失败，用 `uv run --with trailmark python - "{args}"` 重跑同一段代码；若结果为 `[]`，报告 "Trailmark found no supported languages under target" 并返回。
6. 用 `QueryEngine` 运行完整结构化分析：运行 python3 脚本，导入 detect_languages（同上带回退）和 `from trailmark.query.api import QueryEngine`；若 import 失败则用 `uv run --with trailmark python - "{args}"` 重跑。
7. 在脚本中：`target = sys.argv[1]`；`languages = detect_languages(target)`；`engine = QueryEngine.from_directory(target, language="auto")`；`preanalysis = engine.preanalysis()`。
8. 定义 `summarize_subgraph(name, limit=25)`：调用 `engine.subgraph(name)` 取节点，返回 `count` 与 `sample_ids`（前 limit 个节点的 id）；若 `hasattr(engine, "subgraph_edges")` 则加上 `edge_count = len(engine.subgraph_edges(name))`。
9. 解析图：`graph = json.loads(engine.to_json())`；`nodes = graph.get("nodes", {})`；收集 `proxy_nodes`，即 `node.get("kind") == "proxy"` 或 `node.get("origin") == "proxy"` 的节点 id。
10. 组装 payload，包含：`languages`、`summary`（`engine.summary()`）、`preanalysis`、`attack_surface`（`engine.attack_surface()[:25]`）、`hotspots`（`engine.complexity_hotspots(10)[:25]`）、`proxy_nodes`（前 25 个）、`subgraphs`（对 `engine.subgraph_names()` 中每个名字调用 summarize_subgraph）。
11. 若 `hasattr(engine, "type_references")`，加入 `type_reference_samples`：对 `list(nodes)[:25]` 中每个 node_id 取 `engine.type_references(node_id)[:10]`。
12. 打印 `json.dumps(payload, indent=2)`。
13. 校验输出应包含 `languages`、`summary`、`preanalysis`、`hotspots`（可能为空）、`proxy_nodes`（v0.2.x 或无未解析调用时为空；0.5.0+ 可能含 `.trailmark/links.toml` 声明的 `proxy.external:*` 条目）、带计数与样本 ID 的 `subgraphs`。
14. 在 Trailmark 0.5.0+ 上，`attack_surface` 条目可能带 `attributes` 对象（如 `solidity_visibility`、`solidity_overridden_by`），原样透传，下游消费者用它给入口点排序。
15. 某些代码库的某些子图可能为零节点（正常现象），无论结果如何都返回完整 JSON payload。
16. 拒绝以下合理化："summary 分析就够了"（summary 跳过污点、爆炸半径和权限边界数据，需要详细数据时必须跑完整结构化分析）；"跑一遍就够了"（各 pass 相互交叉引用，没有爆炸半径的污点会漏掉关键节点，必须跑全部四类 pass）；"工具没装就手动分析"（手动分析会漏掉工具能捕获的内容，应报告 "trailmark is not installed" 并返回）；"pass 输出为空说明 pass 失败"（某些 pass 对某些代码库本就不产生数据，例如没有权限边界，无论如何都返回完整输出）；"v0.4 字段总是存在"（用户可能仍装着 Trailmark 0.2.x，查询 v0.4-only 方法前必须用 `hasattr()` 探测）。

适用边界 · 注意事项

• 只需要快速概览时（改用 `trailmark-summary`）。
• 做临时性的代码图查询时（直接使用主 `trailmark` 技能）。
• 目标是单个小文件、结构化分析没有价值时。