trailmark-summary

Trailmark 摘要

在目标目录上运行 trailmark analyze --language auto --summary。 这是兼容 v0.2 的工作流；不要仅为生成摘要而要求使用 Trailmark 0.4.0。

适用场景

• Vivisect 第 0 阶段需要在分解前快速了解代码结构
• Galvanize 第 1 阶段需要已检测到的语言和入口点数量
• 在深入分析前快速了解不熟悉的代码库

不适用场景

• 需要运行所有分析阶段的完整结构分析（使用 trailmark-structural）
• 需要详细查询代码图（直接使用主 trailmark 技能）
• 需要热点分数或污点数据（使用 trailmark-structural）

应拒绝的理由

理由	错误原因	必须采取的操作
“我可以改为手动阅读代码”	手动阅读会遗漏基于解析器的语言检测、依赖数据和入口点枚举	安装并运行 trailmark
“语言检测无关紧要”	选择错误的语言会导致分析结果为空或不完整	使用 Trailmark 基于解析器的检测，或使用 --language auto
“不完整的输出也够用了”	缺少三项必需输出（已检测到的语言、入口点、依赖项）中的任何一项，都意味着分析不完整	确认三项都已提供
“没安装工具，我就跳过”	此技能的存在就是为了运行 trailmark	报告缺少安装，而不是跳过

用法

通过 args 参数传入目标目录。

执行

步骤 1：检查 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 或任何安装命令。用户必须自行安装 trailmark。

如果已安装的版本支持，可选择记录版本：

trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null || true

如果缺少版本命令，不要判定失败；较旧的 v0.2.x 版本仍可能 支持摘要工作流。

步骤 2：使用 Trailmark 的解析 API 检测语言。

python3 - "{args}" <<'PY'
import json
import sys

try:
    from trailmark.parse import detect_languages  # canonical location since 0.3.x
except ModuleNotFoundError:
    # v0.2.x predates trailmark.parse; the same function lives in query.api
    from trailmark.query.api import detect_languages

print(json.dumps(detect_languages(sys.argv[1])))
PY

如果导入失败，请使用 uv run --with trailmark python - "{args}" 重新运行相同代码片段。 如果结果为 []，请报告“Trailmark found no supported languages under target”并返回。

步骤 3：使用自动检测运行摘要。

trailmark analyze --language auto --summary {args} 2>&1 || \
  uv run trailmark analyze --language auto --summary {args} 2>&1

步骤 4：验证输出。

输出必须包含以下三项：

1. 步骤 2 检测到的语言
2. 摘要输出中的 Entrypoints: 行
3. 摘要输出中的 Dependencies: 行

如果缺少任何一项，请报告缺失情况。不要捏造输出。

返回已检测到的语言列表以及完整的 Trailmark 摘要输出。 如果有可用的版本字符串，请将其包含在返回的元数据中。