mantis-history

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

History Analyzer (/mantis-history)

历史分析器（/mantis-history）

System Goal

系统目标

Historical Vulnerability Extractor. Analyzes repository's version control system (VCS) history to extract past vulnerabilities, security-related fixes, patches, and associated files, creating a historical learnings database to inform downstream skills.

历史漏洞提取工具。分析代码仓库的版本控制系统（VCS）历史记录，提取过往漏洞、安全相关修复、补丁及关联文件，创建历史经验数据库，为下游技能提供参考。

Command Definition

命令定义

Command:
```
/mantis-history
```
Description: Analyzes repository's version control system (VCS) history to extract past vulnerabilities and fixes, producing a structured historical learnings file (
```
workspace/historical_learnings.jsonl
```
).
Arguments (optional; supplied by the orchestrator, consumed by Block A):
```
--snapshot_root
```
/
```
--snapshot_id
```
/
```
--state_root
```
. History reads VCS logs from the LIVE repository root (Block A step 5), not the snapshot; it uses
```
--state_root
```
only to place its cache/output/script. All absent -> DEGRADED (behaves as today, live cwd).

命令：
```
/mantis-history
```
描述： 分析代码仓库的版本控制系统（VCS）历史记录，提取过往漏洞与修复措施，生成结构化的历史经验文件（
```
workspace/historical_learnings.jsonl
```
）。
参数（可选；由编排器提供，供模块A使用）：
```
--snapshot_root
```
/
```
--snapshot_id
```
/
```
--state_root
```
。历史分析从实时代码仓库根目录读取VCS日志（模块A步骤5），而非快照；仅使用
```
--state_root
```
来存放缓存/输出/脚本。若所有参数缺失，则进入降级模式（与当前行为一致，使用实时工作目录）。

Input/Output Contract

输入/输出约定

Reads:
- ```
workspace/.mantis_state.json
```
  (to track current loop pass).
- Codebase directory structure and key files (to determine stack).
- VCS history logs (commit messages, titles, diffs).
- ```
mantis-summary.md
```
  (optional, if available).
- Internal history analysis cache (optional, if exists).
Writes:
- VCS extraction script (written on-the-fly to workspace).
- ```
workspace/historical_learnings.jsonl
```
  .
- Internal history analysis cache.
- All under
```
--state_root/workspace/
```
  (cache,
```
historical_learnings.jsonl
```
  , extraction script): kept outside the target tree. Optional
```
history_status
```
  marker (
```
UNSUPPORTED_VCS
```
  /
```
PARTIAL_SHALLOW
```
  ).
Preconditions:
- Target repository and VCS logs must be accessible.
Idempotency Guarantee:
- The cache is the source of truth: the output DB is rebuilt from it every run and is never truncated to empty while the cache is non-empty. The cache is invalidated on VCS-history rewrite (
```
_analyzed_head
```
  no longer reachable) or a vcs_type/repo-identity change. On
```
none
```
  /
```
unknown
```
  VCS the stage writes an empty DB +
```
history_status=UNSUPPORTED_VCS
```
  and exits.

读取内容：
- ```
workspace/.mantis_state.json
```
  （用于跟踪当前循环次数）。
- 代码库目录结构与关键文件（用于确定技术栈）。
- VCS历史日志（提交信息、标题、差异内容）。
- ```
mantis-summary.md
```
  （可选，若存在则读取）。
- 内部历史分析缓存（可选，若存在则读取）。
写入内容：
- VCS提取脚本（实时写入工作区）。
- ```
workspace/historical_learnings.jsonl
```
  。
- 内部历史分析缓存。
- 所有内容均存储在
```
--state_root/workspace/
```
  下（缓存、
```
historical_learnings.jsonl
```
  、提取脚本）：保存在目标代码树之外。可选的
```
history_status
```
  标记（
```
UNSUPPORTED_VCS
```
  /
```
PARTIAL_SHALLOW
```
  ）。
前置条件：
- 目标代码仓库与VCS日志必须可访问。
幂等性保证：
- 缓存为可信数据源：每次运行都会从缓存重建输出数据库，且当缓存非空时，绝不会将输出数据库截断为空。当VCS历史被重写（
```
_analyzed_head
```
  不再可达）或vcs_type/仓库标识变更时，缓存将失效。若VCS类型为
```
none
```
  /
```
unknown
```
  ，该阶段会写入空数据库并设置
```
history_status=UNSUPPORTED_VCS
```
  后退出。

Instructions

操作说明

Step 0: Locator Resolution (run first)

步骤0：定位器解析（优先执行）

LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.

CRITICAL for history: the pinned snapshot copy STRIPS

.git

.hg

.repo

, so per Block A step 5 you MUST run every VCS log / diff / blame command in the LIVE repository root (the working directory Mantis was launched in), NOT under CODE_ROOT. Do NOT stop because CODE_ROOT lacks VCS metadata. Write the cache,

workspace/historical_learnings.jsonl

, and your generated extraction script under

--state_root/workspace/

(STATE-RELATIVE) — never into the target tree, so a sync/clean cannot wipe them. Record

active_snapshot.snapshot_id

on entries only for provenance.

Your task is to analyze the codebase architecture, determine what constitutes security-relevant history, and write a script on-the-fly to extract and document historical vulnerabilities from the project's version control system (VCS).

Execute the history analysis stage as follows:

Phase 1: Analyze Codebase and Define Target History:
- Read existing summaries (e.g.
```
mantis-summary.md
```
  if available) or quickly inspect the root codebase structure to understand the primary files, programming languages, and core components.
- Determine what types of historical security issues (e.g., memory corruption, authentication bypass, SQL injection, buffer overflow, or others) are relevant to this project and what keywords or commits should be targeted.
Phase 2: Write a History Extraction Script:
- VCS-support guard (run BEFORE writing/executing the script): Determine
```
vcs_type
```
  from
```
.mantis_state.json
```
```
vcs_info
```
  (or detect it in the LIVE root). If
```
vcs_type
```
  is
```
none
```
  or
```
unknown
```
  , OR the VCS history is otherwise unreachable: write an EMPTY
```
workspace/historical_learnings.jsonl
```
  , set a top-of-file / sidecar marker
```
history_status = "UNSUPPORTED_VCS"
```
  , and EXIT — never fabricate history. For
```
multi-vcs
```
  (.repo): either iterate history per sub-project, or write the empty file with
```
history_status = "UNSUPPORTED_VCS"
```
  rather than run a git-shaped script that errors. For a SHALLOW git clone (
```
git rev-parse --is-shallow-repository
```
  == true): proceed but set
```
history_status = "PARTIAL_SHALLOW"
```
  so downstream stages do NOT read "no historical vuln for this file" as "clean."
- Read the active pass number from the state file
```
workspace/.mantis_state.json
```
  and resolve the current ISO 8601 timestamp.
- Write a script (e.g. Python, bash, or your choice) directly in your workspace that interacts with your repository version control system (VCS) history logs.
- Cost-Efficiency & Scale Optimization: To ensure the historical analysis remains cost-effective and runs efficiently, the script must implement the following optimizations:
  - Commit Message/Description Pre-filtering: Before retrieving diffs, the script should dynamically determine relevant keywords for commit message screening. It can do this by first inspecting the repository's files and languages/domains in scope to establish its primary stack (e.g. software versus hardware/RTL), then either querying an LLM/analysis agent for a tailored list of security/bug keywords or using a broader set of keywords augmented with these specific domain terms. Skip revisions whose messages or titles do not match these relevant keywords to avoid unnecessarily retrieving and analyzing changesets that are irrelevant to the codebase in scope.
  - Diff Filtering and Size Limits: Ignore commits that only touch non-production code (e.g., tests, documentation, or configuration files). Skip commits with excessively large diffs (e.g., more than several thousand lines changed), as they are usually automated formatting changes or massive refactorings rather than discrete security patches.
  - Caching Results (cache is the source of truth): Maintain a local cache (JSON or SQLite) under
```
workspace/
```
    mapping
```
revision_id -> analyzed
```
    , AND storing the full extracted record for each analyzed revision plus an
```
_analyzed_head
```
    high-water mark and the
```
vcs_type
```
    + repo identity the cache was built against. On each run, REBUILD
```
workspace/historical_learnings.jsonl
```
    from the cache (do NOT skip a revision merely because the cache says "analyzed" and then leave the output empty — that is the desync bug). NEVER truncate a non-empty output DB to empty. Only analyze revisions NEWER than
```
_analyzed_head
```
    . Rewrite detection: before trusting the cache, verify
```
_analyzed_head
```
    still resolves in the current LIVE history (git:
```
git cat-file -e <_analyzed_head>
```
    succeeds AND
```
git merge-base --is-ancestor <_analyzed_head> HEAD
```
    ; hg:
```
hg log -r <_analyzed_head>
```
    succeeds). If it does not (force-push / rebase / squash) OR
```
vcs_type
```
    /repo identity changed, INVALIDATE the cache and re-extract from scratch.
  - Batch Processing (Batching Diffs): Instead of making one LLM call per commit diff, the script should batch multiple commit diffs and messages (e.g. 3 to 5 commits) into a single LLM call. Ask the LLM to analyze all commits in the batch and return a JSON array of findings for the batch, reducing request overhead and cost.
  - Model Selection: Use lightweight and cost-efficient models for the initial commit analysis/filtering, and only fall back to heavier model tiers if deeper verification of a suspected vulnerability is needed.
- Detailed Analysis: For revisions or commits that look security-relevant, the script should retrieve the commit diffs and messages/change descriptions.
- LLM/Agent Analysis: The script should make API calls (e.g., via subagent messages or Agent API subcommands) or use an LLM subagent to analyze the changes' diffs and messages to determine whether a revision/commit was a security fix, what component was affected, the vulnerability type, impact, and the mitigation diff. Make sure it uses batching and caching to minimize API calls.
- Missing Information: Do not overindex on the lack of security-related keywords. Many security fixes do not get CVEs, and many security vulnerabilities are fixed without realizing they were vulnerabilities.
- Output Format: Instruct your script to output the extracted findings into a JSONL file named
```
workspace/historical_learnings.jsonl
```
  , matching the following format:

LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.

历史分析关键注意事项：固定快照副本会移除

.git

.hg

.repo

目录，因此根据模块A步骤5，你必须在实时代码仓库根目录（启动Mantis的工作目录）中运行所有VCS日志/差异/追溯命令，而非CODE_ROOT（快照副本）。请勿因CODE_ROOT缺少VCS元数据而停止操作。将缓存、

workspace/historical_learnings.jsonl

及生成的提取脚本写入

--state_root/workspace/

下（相对于状态目录）——绝不要写入目标代码树，以免同步/清理操作将其删除。仅为溯源目的在条目上记录

active_snapshot.snapshot_id

。

你的任务是分析代码库架构，确定哪些属于安全相关历史记录，并实时编写脚本从项目的版本控制系统（VCS）中提取并记录历史漏洞。

按以下步骤执行历史分析阶段：

阶段1：分析代码库并定义目标历史记录：
- 读取现有摘要（例如若存在则读取
```
mantis-summary.md
```
  ）或快速检查根代码库结构，了解主要文件、编程语言及核心组件。
- 确定与该项目相关的历史安全问题类型（例如内存损坏、身份验证绕过、SQL注入、缓冲区溢出等），以及应定位的关键词或提交记录。
阶段2：编写历史提取脚本：
- VCS支持检查（在编写/执行脚本前运行）： 从
```
.mantis_state.json
```
  的
```
vcs_info
```
  中确定
```
vcs_type
```
  （或在实时根目录中检测）。若
```
vcs_type
```
  为
```
none
```
  或
```
unknown
```
  ，或VCS历史记录无法访问：写入空的
```
workspace/historical_learnings.jsonl
```
  ，设置文件顶部/附属标记
```
history_status = "UNSUPPORTED_VCS"
```
  ，然后退出——绝不要伪造历史记录。对于
```
multi-vcs
```
  （.repo）：要么遍历每个子项目的历史记录，要么写入空文件并设置
```
history_status = "UNSUPPORTED_VCS"
```
  ，而非运行会报错的git格式脚本。对于浅克隆的git仓库（
```
git rev-parse --is-shallow-repository
```
  返回true）：继续执行但设置
```
history_status = "PARTIAL_SHALLOW"
```
  ，以便下游阶段不会将“该文件无历史漏洞”解读为“无安全问题”。
- 从状态文件
```
workspace/.mantis_state.json
```
  中读取当前循环次数，并解析当前ISO 8601时间戳。
- 直接在工作区编写脚本（例如Python、bash或你选择的语言），用于与代码仓库的版本控制系统（VCS）历史日志交互。
- 成本效益与规模优化： 为确保历史分析保持成本效益并高效运行，脚本必须实现以下优化：
  - 提交信息/描述预过滤： 在获取差异内容前，脚本应动态确定用于提交信息筛选的相关关键词。可通过先检查仓库的文件、语言/领域范围以确定其核心技术栈（例如软件与硬件/RTL），然后查询LLM/分析代理获取定制化的安全/错误关键词列表，或使用包含这些特定领域术语的更广泛关键词集。跳过消息或标题不匹配这些相关关键词的版本，避免不必要地获取和分析与目标代码库无关的变更集。
  - 差异过滤与大小限制： 忽略仅涉及非生产代码的提交（例如测试、文档或配置文件）。跳过差异内容过大的提交（例如更改超过数千行），因为这些通常是自动格式化变更或大规模重构，而非独立的安全补丁。
  - 结果缓存（缓存为可信数据源）： 在
```
workspace/
```
    下维护本地缓存（JSON或SQLite），映射
```
revision_id -> analyzed
```
    ，并存储每个已分析版本的完整提取记录，以及
```
_analyzed_head
```
    高水位标记和缓存构建所基于的
```
vcs_type
```
    + 仓库标识。每次运行时，从缓存重建
```
workspace/historical_learnings.jsonl
```
    （不要仅因缓存标记为“已分析”就跳过某个版本，导致输出为空——这是同步错误）。绝不要将非空的输出数据库截断为空。仅分析比
```
_analyzed_head
```
    更新的版本。重写检测： 在信任缓存前，验证
```
_analyzed_head
```
    在当前实时历史记录中仍可访问（git：
```
git cat-file -e <_analyzed_head>
```
    成功且
```
git merge-base --is-ancestor <_analyzed_head> HEAD
```
    ；hg：
```
hg log -r <_analyzed_head>
```
    成功）。若不可访问（强制推送/变基/压缩合并）或
```
vcs_type
```
    /仓库标识变更，则使缓存失效并重新从头提取。
  - 批量处理（批量差异）： 不要为每个提交差异调用一次LLM，脚本应将多个提交差异和消息（例如3到5个提交）批量处理为单次LLM调用。请求LLM分析批量中的所有提交并返回JSON格式的批量结果数组，减少请求开销与成本。
  - 模型选择： 使用轻量且成本高效的模型进行初始提交分析/过滤，仅在需要深度验证疑似漏洞时才使用更重量级的模型。
- 详细分析： 对于看起来与安全相关的版本或提交，脚本应获取提交差异及消息/变更描述。
- LLM/代理分析： 脚本应进行API调用（例如通过子代理消息或Agent API子命令）或使用LLM子代理分析变更的差异内容与消息，确定该版本/提交是否为安全修复、受影响的组件、漏洞类型、影响范围及修复差异。确保使用批量处理与缓存来最小化API调用次数。
- 缺失信息处理： 不要过度依赖安全相关关键词的存在。许多安全修复没有CVE编号，且许多安全漏洞在修复时并未被识别为漏洞。
- 输出格式： 指示脚本将提取的结果输出到名为
```
workspace/historical_learnings.jsonl
```
  的JSONL文件中，遵循以下格式：

Historical Learnings Schema Format (

workspace/historical_learnings.jsonl

)

历史经验数据格式（

workspace/historical_learnings.jsonl

）

json

{
  "revision_id": "...",
  "title": "...",
  "description": "...",
  "code_paths": ["file:line_number"],
  "vuln_type": "...",
  "mitigation_diff": "...",
  "cve": "...",
  "history": [
    {
      "stage": "history_extractor",
      "action": "created",
      "details": "Extracted from repository revision history.",
      "pass_number": <current_pass_number>,
      "timestamp": "<current_iso8601_timestamp>"
    }
  ]
}

Phase 3: Execute and Verify:
- Run the script you just wrote to analyze the VCS history, process revisions, and generate the
```
workspace/historical_learnings.jsonl
```
  file.
- Wait for the script to finish and verify that
```
workspace/historical_learnings.jsonl
```
  has been written successfully and contains extracted data.

When complete, notify the user.

json

{
  "revision_id": "...",
  "title": "...",
  "description": "...",
  "code_paths": ["file:line_number"],
  "vuln_type": "...",
  "mitigation_diff": "...",
  "cve": "...",
  "history": [
    {
      "stage": "history_extractor",
      "action": "created",
      "details": "Extracted from repository revision history.",
      "pass_number": <current_pass_number>,
      "timestamp": "<current_iso8601_timestamp>"
    }
  ]
}

阶段3：执行与验证：
- 运行你刚编写的脚本，分析VCS历史记录，处理版本并生成
```
workspace/historical_learnings.jsonl
```
  文件。
- 等待脚本完成，验证
```
workspace/historical_learnings.jsonl
```
  已成功写入且包含提取的数据。

完成后，通知用户。

mantis-history

Original

Translation

History Analyzer (/mantis-history)

历史分析器（/mantis-history）

System Goal

系统目标

Command Definition

命令定义

Input/Output Contract

输入/输出约定

Instructions

操作说明

Step 0: Locator Resolution (run first)

步骤0：定位器解析（优先执行）

Historical Learnings Schema Format (
`workspace/historical_learnings.jsonl`
)

历史经验数据格式（
`workspace/historical_learnings.jsonl`
）

mantis-history

Original

Translation

History Analyzer (/mantis-history)

历史分析器（/mantis-history）

System Goal

系统目标

Command Definition

命令定义

Input/Output Contract

输入/输出约定

Instructions

操作说明

Step 0: Locator Resolution (run first)

步骤0：定位器解析（优先执行）

Historical Learnings Schema Format (workspace/historical_learnings.jsonl)

历史经验数据格式（workspace/historical_learnings.jsonl）

Historical Learnings Schema Format (
`workspace/historical_learnings.jsonl`
)

历史经验数据格式（
`workspace/historical_learnings.jsonl`
）